How redragonx/open-rnet works
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 Docs · can2RNET.py CAN Library · reference Reference · rnet_utils.py Protocol Utils
Components 21
Analysis
Reverse-engineering workspace for captures and firmware.
- Firmware Analysis · Scripts that inspect encryption, keys, and embedded configuration structures.
analysis/firmware - Protocol 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 · Low-level Python interface for sending and receiving R-Net CAN frames over SocketCAN.
lib/can2RNET.py - Config Parser · Parses .R-net files into structured representations and extracted settings.
tools/rnet_config_parser.py - Programmer · Low-level read/write tooling for the POP/programmer protocol.
tools/rnet_programmer.py - Self Program · Interactive chair self-programming workflow.
tools/rnet_self_program.py - OBP Mode · Enables and exercises on-board programming mode.
tools/rnet_obp_mode.py - POP Shell · Interactive shell for inspecting and testing protocol messages.
tools/rnet_pop_shell.py - JSM Emu · Emulates the joystick module to drive the bus and test responses.
tools/emulate_jsm.py - Protocol Utils · Shared decoding and protocol helper functions used by the Python tools.
tools/rnet_utils.py
Hardware
Physical interface and CAN bridge layer.
- CAN Bridge · Physical path between software and the wheelchair bus via SocketCAN or serial-to-CAN bridging.
- PiCAN2 / SocketCAN · Linux SocketCAN path used with Raspberry Pi and PiCAN2 hardware.
- Arduino SLCAN · Serial-to-CAN firmware and sketchbook used as an alternative CAN bridge.
hardware/arduino_slcan - CAN 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 · Human-readable JSON and text outputs derived from raw .R-net files.
configs/parsed - Docs · Architecture-level protocol guides, safety notes, and operational documentation.
docs - Reference · Frame dictionaries, command references, and controller layout notes.
reference
Evidence
Raw captures, firmware dumps, and config corpora.
- Captures · Raw packet captures, logs, and transaction traces from real chairs and protocol experiments.
captures - Firmware · Extracted firmware images used to study embedded behavior and secrets.
firmware - Raw Configs · Original vendor .R-net configuration files from multiple chair models.
configs/raw
Legacy
Experimental and upstream control code.
- Legacy Code · Upstream and historical control experiments including IP-based and joystick-following variants.
contrib/can2RNET
Connections 30
- 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.