# redragonx/open-rnet architecture

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

- Interactive diagram: https://gitdiagram.com/redragonx/open-rnet
- Repository: https://github.com/redragonx/open-rnet

## Overview

1. **Overall shape**
   This repository is a research-and-tooling codebase for reverse engineering the R-Net wheelchair CAN bus. It is not a single application; it is a collection of evidence, analysis scripts, protocol documentation, and practical control/programming tools built around one core protocol model.

2. **Core runtime boundary**
   The main executable boundary is the Python tooling in `tools/` plus the low-level CAN library in `lib/can2RNET.py`. These scripts talk to a live R-Net bus over Linux SocketCAN, and they are the parts you would diagram as the “active system” that sends and receives frames.

3. **Hardware/interface layer**
   The repo supports two physical interface paths:
   - Raspberry Pi + PiCAN2 via SocketCAN
   - Arduino SLCAN firmware in `hardware/arduino_slcan/` for serial-to-CAN bridging  
   The shell scripts in `hardware/scripts/` bring CAN interfaces up/down and support specific power-on workflows. This is the boundary between software and the wheelchair bus.

4. **Protocol control tools**
   `tools/` contains the user-facing operations:
   - `rnet_self_program.py` for interactive chair self-programming
   - `rnet_programmer.py` for low-level read/write via the POP/programmer protocol
   - `rnet_obp_mode.py` for on-board programming mode
   - `rnet_pop_shell.py` for interactive protocol inspection
   - `emulate_jsm.py` for joystick module emulation
   - `rnet_config_parser.py` for `.R-net` file parsing
   - `rnet_utils.py` for decoding and general protocol helpers  
   These tools form the repository’s practical “control plane.”

5. **Main data flow: captures to protocol knowledge**
   The `captures/` directory holds raw packet captures and logs from real chairs, bus transactions, power-up sequences, programmer interactions, and Bluetooth/display behavior. These are the primary source data for reverse engineering. The analysis scripts and documentation derive frame meanings, timing, and device behavior from these captures.

6. **Analysis pipeline**
   `analysis/` is the reverse-engineering workspace. It contains separate sub-areas for:
   - firmware analysis (`analysis/firmware/`)
   - protocol capture parsing and extraction (`analysis/protocol/`)  
   The scripts here are investigative, not production tooling. They feed findings into `docs/`, `reference/`, and the parsed config outputs under `configs/parsed/`.

7. **Firmware artifacts and reverse engineering boundary**
   `firmware/` contains dumped firmware images, while `analysis/firmware/` contains scripts that inspect encryption, configuration structures, and embedded keys. This subsystem is about extracting secrets and behavior from device firmware rather than observing the bus externally. It supports the protocol and config tooling by revealing how device configuration is encoded.

8. **Configuration corpus**
   `configs/raw/` stores original `.R-net` files taken from multiple chair models and variants, while `configs/parsed/` holds extracted human-readable representations in JSON and text. This is a key data-model boundary: raw vendor config blobs in, structured settings out. The parser in `tools/rnet_config_parser.py` and related analysis scripts operate on this corpus.

9. **Documentation as architecture output**
   `docs/` and `reference/` are not just guides; they are the canonical knowledge layer produced by the reverse-engineering effort. They describe the R-Net frame dictionary, programmer protocol, display protocol, security findings, safety restrictions, and device catalogs. For an architecture diagram, these docs sit between raw evidence and the tooling, capturing the project’s inferred protocol model.

10. **Upstream and experimental code**
   `contrib/can2RNET/` contains upstream and legacy control code, including joystick-following and IP-based control experiments. This is a separate lineage from the main `tools/` interface and is best treated as experimental or historical implementation space. It demonstrates alternate control strategies, but it is not the main maintained boundary.

11. **Operational flow**
   In practice, the flow is:
   raw captures/firmware/configs → analysis scripts and reverse engineering → protocol docs and parsed config artifacts → Python tools using `lib/can2RNET.py` → live CAN bus via SocketCAN or SLCAN hardware.  
   That is the central architecture of the repository.

12. **External dependencies and infrastructure**
   The materially important external pieces are Linux SocketCAN, `candump`/can-utils, the Arduino CAN shield or PiCAN2 hardware, and real wheelchair devices. No server-side infrastructure is central to the repo; the system is mostly local tooling connected to physical CAN hardware.

13. **Safety/operational constraint**
   The project is explicitly safety-critical: commands can directly affect wheelchair motion and programming state. That means the architecture includes a human-in-the-loop boundary, with emergency stop, spotter, and test-stand assumptions called out in the docs. This is important to capture because control logic and safety are inseparable here.

Main entry points: [`docs`](https://github.com/redragonx/open-rnet/tree/main/docs) (Docs), [`lib/can2RNET.py`](https://github.com/redragonx/open-rnet/blob/main/lib/can2RNET.py) (CAN Library), [`reference`](https://github.com/redragonx/open-rnet/tree/main/reference) (Reference), [`tools/rnet_utils.py`](https://github.com/redragonx/open-rnet/blob/main/tools/rnet_utils.py) (Protocol Utils)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_analysis["Analysis"]
  node_analysis_firmware["Firmware Analysis<br/>reverse engineering"]
  node_analysis_protocol["Protocol Analysis<br/>trace analysis"]
end

subgraph group_runtime["Runtime"]
  node_rnet_lib["CAN Library<br/>bus client<br/>[can2RNET.py]"]
  node_tools_parser["Config Parser"]
  node_tools_programmer["Programmer<br/>control tool<br/>[rnet_programmer.py]"]
  node_tools_selfprog["Self Program<br/>control tool"]
  node_tools_obp["OBP Mode<br/>control tool<br/>[rnet_obp_mode.py]"]
  node_tools_shell["POP Shell<br/>inspection tool<br/>[rnet_pop_shell.py]"]
  node_tools_emu["JSM Emu<br/>emulator<br/>[emulate_jsm.py]"]
  node_tools_utils["Protocol Utils<br/>helpers<br/>[rnet_utils.py]"]
end

subgraph group_hardware["Hardware"]
  node_can_hw{{"CAN Bridge<br/>interface layer"}}
  node_pican_socketcan(("PiCAN2 / SocketCAN<br/>bus interface"))
  node_slcan_arduino["Arduino SLCAN<br/>bridge firmware"]
  node_hw_scripts["CAN Scripts<br/>ops scripts"]
end

subgraph group_knowledge["Knowledge"]
  node_parsed_configs[("Parsed Configs<br/>structured configs")]
  node_docs["Docs<br/>protocol knowledge"]
  node_reference["Reference<br/>catalogs"]
end

subgraph group_data["Evidence"]
  node_captures[("Captures<br/>evidence corpus")]
  node_firmware[("Firmware<br/>binary dumps")]
  node_raw_configs[("Raw Configs<br/>config corpus")]
end

subgraph group_legacy["Legacy"]
  node_contrib["Legacy Code<br/>experimental lineage"]
end

node_captures -->|"parsed by"| node_analysis_protocol
node_firmware -->|"inspected by"| node_analysis_firmware
node_raw_configs -->|"input to"| node_tools_parser
node_tools_parser -->|"writes"| node_parsed_configs
node_analysis_protocol -->|"feeds"| node_docs
node_analysis_firmware -->|"feeds"| node_docs
node_analysis_protocol -->|"feeds"| node_reference
node_analysis_firmware -->|"feeds"| node_reference
node_docs -->|"guides"| node_tools_programmer
node_docs -->|"guides"| node_tools_selfprog
node_docs -->|"guides"| node_tools_obp
node_docs -->|"guides"| node_tools_emu
node_reference -->|"informs"| node_rnet_lib
node_tools_programmer -->|"uses"| node_rnet_lib
node_tools_selfprog -->|"uses"| node_rnet_lib
node_tools_obp -->|"uses"| node_rnet_lib
node_tools_shell -->|"uses"| node_rnet_lib
node_tools_emu -->|"uses"| node_rnet_lib
node_tools_utils -->|"supports"| node_tools_programmer
node_tools_utils -->|"supports"| node_tools_selfprog
node_tools_utils -->|"supports"| node_tools_obp
node_hw_scripts -->|"configures"| node_can_hw
node_slcan_arduino -->|"bridges"| node_can_hw
node_pican_socketcan -->|"bridges"| node_can_hw
node_can_hw -->|"connects"| node_rnet_lib
node_contrib -.->|"historical lineage"| node_tools_emu
node_contrib -.->|"derives from"| node_rnet_lib
node_captures -->|"evidence for"| node_docs
node_parsed_configs -->|"corroborates"| node_docs
node_docs -->|"summarizes"| node_reference

click node_captures "https://github.com/redragonx/open-rnet/tree/main/captures"
click node_firmware "https://github.com/redragonx/open-rnet/tree/main/firmware"
click node_raw_configs "https://github.com/redragonx/open-rnet/tree/main/configs/raw"
click node_parsed_configs "https://github.com/redragonx/open-rnet/tree/main/configs/parsed"
click node_analysis_firmware "https://github.com/redragonx/open-rnet/tree/main/analysis/firmware"
click node_analysis_protocol "https://github.com/redragonx/open-rnet/tree/main/analysis/protocol"
click node_rnet_lib "https://github.com/redragonx/open-rnet/blob/main/lib/can2RNET.py"
click node_tools_parser "https://github.com/redragonx/open-rnet/blob/main/tools/rnet_config_parser.py"
click node_tools_programmer "https://github.com/redragonx/open-rnet/blob/main/tools/rnet_programmer.py"
click node_tools_selfprog "https://github.com/redragonx/open-rnet/blob/main/tools/rnet_self_program.py"
click node_tools_obp "https://github.com/redragonx/open-rnet/blob/main/tools/rnet_obp_mode.py"
click node_tools_shell "https://github.com/redragonx/open-rnet/blob/main/tools/rnet_pop_shell.py"
click node_tools_emu "https://github.com/redragonx/open-rnet/blob/main/tools/emulate_jsm.py"
click node_tools_utils "https://github.com/redragonx/open-rnet/blob/main/tools/rnet_utils.py"
click node_slcan_arduino "https://github.com/redragonx/open-rnet/tree/main/hardware/arduino_slcan"
click node_hw_scripts "https://github.com/redragonx/open-rnet/tree/main/hardware/scripts"
click node_docs "https://github.com/redragonx/open-rnet/tree/main/docs"
click node_reference "https://github.com/redragonx/open-rnet/tree/main/reference"
click node_contrib "https://github.com/redragonx/open-rnet/tree/main/contrib/can2RNET"

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_analysis_firmware,node_analysis_protocol toneBlue
class node_rnet_lib,node_tools_parser,node_tools_programmer,node_tools_selfprog,node_tools_obp,node_tools_shell,node_tools_emu,node_tools_utils toneAmber
class node_can_hw,node_pican_socketcan,node_slcan_arduino,node_hw_scripts toneMint
class node_parsed_configs,node_docs,node_reference toneRose
class node_captures,node_firmware,node_raw_configs toneIndigo
class node_contrib toneTeal
```

## Components

### Analysis

Reverse-engineering workspace for captures and firmware.

- [Firmware Analysis](https://github.com/redragonx/open-rnet/tree/main/analysis/firmware): reverse engineering · Scripts that inspect encryption, keys, and embedded configuration structures. · `analysis/firmware`
- [Protocol Analysis](https://github.com/redragonx/open-rnet/tree/main/analysis/protocol): trace analysis · Scripts that parse captures and extract protocol behavior and frame meanings. · `analysis/protocol`

### Runtime

Live Python tooling and protocol library that interact with the chair bus.

- [CAN Library](https://github.com/redragonx/open-rnet/blob/main/lib/can2RNET.py): bus client · Low-level Python interface for sending and receiving R-Net CAN frames over SocketCAN. · `lib/can2RNET.py`
- [Config Parser](https://github.com/redragonx/open-rnet/blob/main/tools/rnet_config_parser.py): parser · Parses .R-net files into structured representations and extracted settings. · `tools/rnet_config_parser.py`
- [Programmer](https://github.com/redragonx/open-rnet/blob/main/tools/rnet_programmer.py): control tool · Low-level read/write tooling for the POP/programmer protocol. · `tools/rnet_programmer.py`
- [Self Program](https://github.com/redragonx/open-rnet/blob/main/tools/rnet_self_program.py): control tool · Interactive chair self-programming workflow. · `tools/rnet_self_program.py`
- [OBP Mode](https://github.com/redragonx/open-rnet/blob/main/tools/rnet_obp_mode.py): control tool · Enables and exercises on-board programming mode. · `tools/rnet_obp_mode.py`
- [POP Shell](https://github.com/redragonx/open-rnet/blob/main/tools/rnet_pop_shell.py): inspection tool · Interactive shell for inspecting and testing protocol messages. · `tools/rnet_pop_shell.py`
- [JSM Emu](https://github.com/redragonx/open-rnet/blob/main/tools/emulate_jsm.py): emulator · Emulates the joystick module to drive the bus and test responses. · `tools/emulate_jsm.py`
- [Protocol Utils](https://github.com/redragonx/open-rnet/blob/main/tools/rnet_utils.py): helpers · Shared decoding and protocol helper functions used by the Python tools. · `tools/rnet_utils.py`

### Hardware

Physical interface and CAN bridge layer.

- **CAN Bridge**: interface layer · Physical path between software and the wheelchair bus via SocketCAN or serial-to-CAN bridging.
- **PiCAN2 / SocketCAN**: bus interface · Linux SocketCAN path used with Raspberry Pi and PiCAN2 hardware.
- [Arduino SLCAN](https://github.com/redragonx/open-rnet/tree/main/hardware/arduino_slcan): bridge firmware · Serial-to-CAN firmware and sketchbook used as an alternative CAN bridge. · `hardware/arduino_slcan`
- [CAN Scripts](https://github.com/redragonx/open-rnet/tree/main/hardware/scripts): ops scripts · Shell scripts for bringing interfaces up/down and managing power-on workflows. · `hardware/scripts`

### Knowledge

Canonical protocol docs, references, and parsed artifacts.

- [Parsed Configs](https://github.com/redragonx/open-rnet/tree/main/configs/parsed): structured configs · Human-readable JSON and text outputs derived from raw .R-net files. · `configs/parsed`
- [Docs](https://github.com/redragonx/open-rnet/tree/main/docs): protocol knowledge · Architecture-level protocol guides, safety notes, and operational documentation. · `docs`
- [Reference](https://github.com/redragonx/open-rnet/tree/main/reference): catalogs · Frame dictionaries, command references, and controller layout notes. · `reference`

### Evidence

Raw captures, firmware dumps, and config corpora.

- [Captures](https://github.com/redragonx/open-rnet/tree/main/captures): evidence corpus · Raw packet captures, logs, and transaction traces from real chairs and protocol experiments. · `captures`
- [Firmware](https://github.com/redragonx/open-rnet/tree/main/firmware): binary dumps · Extracted firmware images used to study embedded behavior and secrets. · `firmware`
- [Raw Configs](https://github.com/redragonx/open-rnet/tree/main/configs/raw): config corpus · Original vendor .R-net configuration files from multiple chair models. · `configs/raw`

### Legacy

Experimental and upstream control code.

- [Legacy Code](https://github.com/redragonx/open-rnet/tree/main/contrib/can2RNET): experimental lineage · Upstream and historical control experiments including IP-based and joystick-following variants. · `contrib/can2RNET`

## Connections

- Captures → Protocol Analysis: parsed by · Trace captures are mined for frame structure, timing, and device behavior.
- Firmware → Firmware Analysis: inspected by · Firmware dumps are used for encryption and embedded-structure analysis.
- Raw Configs → Config Parser: input to · Raw .R-net files are converted into structured representations.
- Config Parser → Parsed Configs: writes · Parser outputs populate the parsed config corpus.
- Protocol Analysis → Docs: feeds · Recovered protocol knowledge is documented for the project.
- Firmware Analysis → Docs: feeds · Firmware findings are written into reverse-engineering documentation.
- Protocol Analysis → Reference: feeds · Extracted frame and command knowledge becomes reference material.
- Firmware Analysis → Reference: feeds · Firmware-derived keys, encodings, and structures inform references.
- Docs → Programmer: guides · Operational docs explain how to use programmer workflows safely.
- Docs → Self Program: guides · Docs describe self-programming workflows and constraints.
- Docs → OBP Mode: guides · Docs explain enabling and using on-board programming mode.
- Docs → JSM Emu: guides · Documentation supports emulator behavior and expected bus responses.
- Reference → CAN Library: informs · Protocol dictionaries and command references shape the low-level CAN client.
- Programmer → CAN Library: uses · Programmer tooling sends and receives frames through the shared library.
- Self Program → CAN Library: uses · Self-programming workflow builds on the shared CAN client.
- OBP Mode → CAN Library: uses · OBP mode tooling talks through the low-level library.
- POP Shell → CAN Library: uses · Interactive shell is a thin protocol client over the CAN library.
- JSM Emu → CAN Library: uses · JSM emulation sends protocol frames via the shared library.
- Protocol Utils → Programmer: supports · Helpers provide decoding and common protocol operations.
- Protocol Utils → Self Program: supports · Shared helpers reduce protocol duplication across tools.
- Protocol Utils → OBP Mode: supports · Utility functions support mode handling and frame decoding.
- CAN Scripts → CAN Bridge: configures · Shell scripts bring up, reset, and power-cycle the CAN interface.
- Arduino SLCAN → CAN Bridge: bridges · Arduino firmware provides a serial-to-CAN bridge path.
- PiCAN2 / SocketCAN → CAN Bridge: bridges · PiCAN2 with SocketCAN is the primary direct bus interface path.
- CAN Bridge → CAN Library: connects · The CAN client relies on a live interface to reach the wheelchair bus.
- Legacy Code → JSM Emu: historical lineage · Legacy code explores earlier joystick and control experiments.
- Legacy Code → CAN Library: derives from · Upstream code shares the same CAN client lineage.
- Captures → Docs: evidence for · Captured real-world traffic underpins the documented protocol model.
- Parsed Configs → Docs: corroborates · Structured configs reinforce catalog and file-format documentation.
- Docs → Reference: summarizes · Documentation and reference material form the knowledge layer.
