# freespacenav/spacenavd architecture

> Architecture diagram of the GitHub repository freespacenav/spacenavd, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/freespacenav/spacenavd
- Repository: https://github.com/freespacenav/spacenavd

## Overview

spacenavd is a user-space driver daemon for six-degree-of-freedom input devices. Its main workflow is to discover and read device input, normalize and transform events, apply configuration-driven mappings and actions, then dispatch events to applications over the spacenav Unix-socket protocol or the legacy Magellan X11 protocol. Clients can also query devices and change settings through the Unix protocol. The README documents compatibility and configuration capabilities; some subsystem links below rely on that documentation because their implementation was not sampled.

Main entry points: [`src/spnavd.c`](https://github.com/freespacenav/spacenavd/blob/master/src/spnavd.c) (Daemon loop), [`src/dev.c`](https://github.com/freespacenav/spacenavd/blob/master/src/dev.c) (Device manager), [`src/proto_unix.c`](https://github.com/freespacenav/spacenavd/blob/master/src/proto_unix.c) (Unix socket protocol), [`src/proto_x11.c`](https://github.com/freespacenav/spacenavd/blob/master/src/proto_x11.c) (Magellan X11 protocol)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_daemon["Daemon control"]
  node_daemon["Daemon loop<br/>[spnavd.c]"]
  node_logging["Logging<br/>[logger.c]"]
end

subgraph group_devices["Device input"]
  node_device_manager["Device manager<br/>[dev.c]"]
  node_serial["Serial backend<br/>[dev_serial.c]"]
  node_usb_linux["Linux USB backend<br/>[dev_usb_linux.c]"]
  node_usb_freebsd["FreeBSD USB backend<br/>[dev_usb_freebsd.c]"]
  node_hotplug["Platform hotplug<br/>[hotplug.h]"]
end

subgraph group_events["Event processing"]
  node_event_queue["Device event queue<br/>[event.c]"]
  node_event_transform["Mapping and actions<br/>[event.c]"]
  node_keyboard_emulation["Keyboard emulation<br/>[kbemu.c]"]
end

subgraph group_protocols["Client protocols"]
  node_unix_protocol["Unix socket protocol<br/>[proto_unix.c]"]
  node_x11_protocol["Magellan X11 protocol<br/>[proto_x11.c]"]
  node_clients["Client registry<br/>[client.c]"]
  node_unix_wire["Unix wire format<br/>[proto.h]"]
  node_x_detection["X display detection<br/>[xdetect.h]"]
end

subgraph group_settings["Configuration"]
  node_configuration["Settings and persistence<br/>[cfgfile.c]"]
end

node_applications(("Client applications"))
node_sixdof(("6-DOF device"))
node_configfile["Configuration file"]

node_applications -->|"connects"| node_unix_protocol
node_applications -.->|"uses legacy protocol"| node_x11_protocol
node_sixdof -->|"provides input"| node_device_manager
node_configfile -->|"loads and saves"| node_configuration
node_daemon -->|"loads settings"| node_configuration
node_daemon -->|"manages devices"| node_device_manager
node_daemon -->|"handles changes"| node_hotplug
node_daemon -->|"processes queued input"| node_event_queue
node_daemon -->|"runs service"| node_unix_protocol
node_daemon -.->|"runs compatibility service"| node_x11_protocol
node_device_manager -->|"reads serial input"| node_serial
node_device_manager -->|"reads USB input"| node_usb_linux
node_device_manager -->|"reads USB input"| node_usb_freebsd
node_device_manager -->|"queues input"| node_event_queue
node_event_queue -->|"supplies input events"| node_event_transform
node_event_transform -->|"emits mapped keys"| node_keyboard_emulation
node_event_transform -->|"broadcasts events"| node_unix_protocol
node_event_transform -.->|"broadcasts events"| node_x11_protocol
node_unix_protocol -->|"registers clients"| node_clients
node_x11_protocol -.->|"registers clients"| node_clients
node_unix_protocol -->|"encodes requests"| node_unix_wire
node_unix_protocol -->|"reads and changes settings"| node_configuration
node_unix_protocol -->|"queries devices"| node_device_manager
node_x11_protocol -.->|"detects display"| node_x_detection
node_daemon -->|"records status"| node_logging

click node_daemon "https://github.com/freespacenav/spacenavd/blob/master/src/spnavd.c"
click node_device_manager "https://github.com/freespacenav/spacenavd/blob/master/src/dev.c"
click node_serial "https://github.com/freespacenav/spacenavd/blob/master/src/dev_serial.c"
click node_usb_linux "https://github.com/freespacenav/spacenavd/blob/master/src/dev_usb_linux.c"
click node_usb_freebsd "https://github.com/freespacenav/spacenavd/blob/master/src/dev_usb_freebsd.c"
click node_hotplug "https://github.com/freespacenav/spacenavd/blob/master/src/hotplug.h"
click node_event_queue "https://github.com/freespacenav/spacenavd/blob/master/src/event.c"
click node_event_transform "https://github.com/freespacenav/spacenavd/blob/master/src/event.c"
click node_keyboard_emulation "https://github.com/freespacenav/spacenavd/blob/master/src/kbemu.c"
click node_unix_protocol "https://github.com/freespacenav/spacenavd/blob/master/src/proto_unix.c"
click node_x11_protocol "https://github.com/freespacenav/spacenavd/blob/master/src/proto_x11.c"
click node_clients "https://github.com/freespacenav/spacenavd/blob/master/src/client.c"
click node_unix_wire "https://github.com/freespacenav/spacenavd/blob/master/src/proto.h"
click node_x_detection "https://github.com/freespacenav/spacenavd/blob/master/src/xdetect.h"
click node_configuration "https://github.com/freespacenav/spacenavd/blob/master/src/cfgfile.c"
click node_logging "https://github.com/freespacenav/spacenavd/blob/master/src/logger.c"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_daemon,node_logging,node_applications toneBlue
class node_device_manager,node_serial,node_usb_linux,node_usb_freebsd,node_hotplug toneAmber
class node_event_queue,node_event_transform,node_keyboard_emulation toneMint
class node_unix_protocol,node_x11_protocol,node_clients,node_unix_wire,node_x_detection toneRose
class node_configuration,node_sixdof,node_configfile toneIndigo
```

## Components

### Daemon control

- [Daemon loop](https://github.com/freespacenav/spacenavd/blob/master/src/spnavd.c): `src/spnavd.c`
- [Logging](https://github.com/freespacenav/spacenavd/blob/master/src/logger.c): `src/logger.c`

### Device input

- [Device manager](https://github.com/freespacenav/spacenavd/blob/master/src/dev.c): `src/dev.c`
- [Serial backend](https://github.com/freespacenav/spacenavd/blob/master/src/dev_serial.c): `src/dev_serial.c`
- [Linux USB backend](https://github.com/freespacenav/spacenavd/blob/master/src/dev_usb_linux.c): `src/dev_usb_linux.c`
- [FreeBSD USB backend](https://github.com/freespacenav/spacenavd/blob/master/src/dev_usb_freebsd.c): `src/dev_usb_freebsd.c`
- [Platform hotplug](https://github.com/freespacenav/spacenavd/blob/master/src/hotplug.h): `src/hotplug.h`

### Event processing

- [Device event queue](https://github.com/freespacenav/spacenavd/blob/master/src/event.c): `src/event.c`
- [Mapping and actions](https://github.com/freespacenav/spacenavd/blob/master/src/event.c): `src/event.c`
- [Keyboard emulation](https://github.com/freespacenav/spacenavd/blob/master/src/kbemu.c): `src/kbemu.c`

### Client protocols

- [Unix socket protocol](https://github.com/freespacenav/spacenavd/blob/master/src/proto_unix.c): `src/proto_unix.c`
- [Magellan X11 protocol](https://github.com/freespacenav/spacenavd/blob/master/src/proto_x11.c): `src/proto_x11.c`
- [Client registry](https://github.com/freespacenav/spacenavd/blob/master/src/client.c): `src/client.c`
- [Unix wire format](https://github.com/freespacenav/spacenavd/blob/master/src/proto.h): `src/proto.h`
- [X display detection](https://github.com/freespacenav/spacenavd/blob/master/src/xdetect.h): `src/xdetect.h`

### Configuration

- [Settings and persistence](https://github.com/freespacenav/spacenavd/blob/master/src/cfgfile.c): `src/cfgfile.c`

### Other components

- **Client applications**
- **6-DOF device**
- **Configuration file**

## Connections

- Client applications → Unix socket protocol: connects
- Client applications → Magellan X11 protocol: uses legacy protocol
- 6-DOF device → Device manager: provides input
- Configuration file → Settings and persistence: loads and saves
- Daemon loop → Settings and persistence: loads settings
- Daemon loop → Device manager: manages devices
- Daemon loop → Platform hotplug: handles changes
- Daemon loop → Device event queue: processes queued input
- Daemon loop → Unix socket protocol: runs service
- Daemon loop → Magellan X11 protocol: runs compatibility service
- Device manager → Serial backend: reads serial input
- Device manager → Linux USB backend: reads USB input
- Device manager → FreeBSD USB backend: reads USB input
- Device manager → Device event queue: queues input
- Device event queue → Mapping and actions: supplies input events
- Mapping and actions → Keyboard emulation: emits mapped keys
- Mapping and actions → Unix socket protocol: broadcasts events
- Mapping and actions → Magellan X11 protocol: broadcasts events
- Unix socket protocol → Client registry: registers clients
- Magellan X11 protocol → Client registry: registers clients
- Unix socket protocol → Unix wire format: encodes requests
- Unix socket protocol → Settings and persistence: reads and changes settings
- Unix socket protocol → Device manager: queries devices
- Magellan X11 protocol → X display detection: detects display
- Daemon loop → Logging: records status