Fejemis Bridge ROS2

Back to Fejemis ROS2 Software

Fejemis Bridge — Design, flow and file map

Purpose

`fejemis_bridge` translates the Teensy serial protocol into typed ROS2 messages and back. This page explains the runtime flow, the core files to edit, and the small number of extension points developers need.

Overview

The bridge runs as a ROS2 node that creates two serial sources (`front` and `drive`). Each source registers lightweight "proxies" that convert between device text prefixes and ROS messages. Low-level framing, CRC, confirmation and retry are handled by the shared `raubase` serial layer.

Primary components

• `bridge` node — wrapper around `raubase::SerialBridge` that registers sources and parameters. (`src/bridge/main.cpp`, `include/fejemis_bridge/bridge.hpp`)
• `SerialSource` subclasses — device-specific handlers that run the TRX loop and own proxies (`include/fejemis_bridge/sources/*`, `src/bridge/sources/*`).
• Proxies — single-purpose adapters mapping device prefixes ↔ ROS messages (`include/fejemis_bridge/proxies.hpp`, `src/bridge/proxies/*`).
• `raubase` serial core — framing, CRC, confirm/resend, queues (`deps/raubase_core/.../message.hpp`, `.../source_txrx.cpp`).

Key files (quick map)

• `include/fejemis_bridge/bridge.hpp` — registers `FrontTeensy` and `DriveTeensy`.
• `src/bridge/sources/*.cpp` — source constructors (where proxies are registered).
• `include/fejemis_bridge/proxies.hpp` and `src/bridge/proxies/*.cpp` — proxy declarations and conversions.
• `config/bridge.yaml` — runtime parameters (proxies, rates, device defaults).

Runtime flow (short)

1. Bridge constructs sources and registers proxies. 2. Each source runs a TRX loop: read bytes → assemble framed line → validate CRC → dispatch to proxy; and handle TX queue → send messages → wait for confirm if requested. 3. Inbound: device line → proxy `from_device()` → publish ROS message. 4. Outbound: ROS message → proxy `to_device()` → enqueue `Message` → TRX loop sends (CRC added).

Message framing (exact)

• Frame start: `;` (CRC prefix starts immediately after).
• CRC: 3-char prefix `;NN` (computed by `Message::generateCRC`).
• Terminator: `\n` (newline).
• Confirmation: messages may request confirmation (`!` flag); confirmations are matched to queue head and cause the entry to be popped.

Proxies and topics (simple)

Proxies are tiny adapters. For each proxy you should know three things: 1. Device prefix it handles (e.g. `hbt`, `fwl`, `manage`). 2. Which ROS message type it publishes/subscribes. 3. Which source (front/drive) it is registered with.

Inbound example:

• `;NNhbt 123 1\n` → `SerialSource` strips CRC → finds `hbt` proxy → `hbt` proxy parses payload → publishes `Heartbeat` message.

Outbound example:

• Publish `DriveManage` with `cmd_type=START_MOTORS` → Drive proxy formats `manage start` → bridge sends `;NNmanage start\n` to Teensy.

Where to find exact topic names: open the proxy implementation in `src/bridge/proxies/*.cpp` — it shows the publisher/subscriber topic strings and message types used.

Extension (what to edit)

To add a new device message:

• Add or reuse a ROS `msg` (if needed).
• Implement conversions in a new proxy (`src/bridge/proxies/YourProxy.cpp`).
• Declare the proxy in `include/fejemis_bridge/proxies.hpp` and register it in the appropriate source constructor (`src/bridge/sources/*`).
• Optionally add parameters to `config/bridge.yaml`.

Troubleshooting (short)

• CRC failures: check RX logs (CRC check messages) — invalid CRC means device or framing differs.
• Missing confirmations: inspect `source_txrx.cpp` logs for timeouts and resend messages; check `timeout_confirm` / `max_resend` in `SourceConfig`.
• Swapped serial ports: verify `front_device` and `drive_device` parameters and use `/dev/serial/by-id/*` symlinks if needed.

Quick checklist to include in the wiki

• Parameters & defaults: `front_device`, `drive_device`, `timeout_confirm`, `max_resend` (see `bridge.hpp` and `source` config).
• Proxy → prefix → topic → msg table (optional, can be generated from `src/bridge/proxies`).
• One inbound and one outbound framed example (in Message framing section).