Skip to main content
Stretch Lab

Body API Map

Parsed from stretch_body_ii/src/ with transport, RPC, endpoint, and communication-chain details.

26
Modules
59
Classes
12,132
Lines (shown)
41
Class RPC Maps

Transport Layer

transport stack including backend behavior, framing, checksum, line-coding notes, and integration options for native extensions.

transport

Python backend
TransportPySerial via aioserial.AioSerial; baud not explicitly set in Python path.
C backend
TransportCSerial via libtransport.so queue thread; open config uses raw serial mode.
Framing
Shared Hello transport framing with encoding, Modbus, and 0x00 packet marker.

Notes

  • Nominal line coding is treated as 2,000,000 baud on the firmware side.
  • C backend implementation notes include B115200 open flags in transport_framing.cpp.
  • RPC limits: 1024-byte max payload, 64-byte raw frame ceiling, 58-byte v1 data chunks.

MCU Endpoint Mapping

Linux device paths mapped to board roles and fixed C-backend queue IDs (qid 0-5).

MCU endpoint and board mapping
Device pathBoardFirmwareqid
/dev/hello-motor-omni-0Omni wheel board 0Stepper0
/dev/hello-motor-omni-1Omni wheel board 1Stepper1
/dev/hello-motor-omni-2Omni wheel board 2Stepper2
/dev/hello-motor-armArm boardStepper3
/dev/hello-motor-liftLift boardStepper4
/dev/hello-power-periphPower + IMU boardPowerPeriph5

Client-Server Architecture

Three strict REQ/REP channels in Stretch Body: admin (5556), command (5557), and status (5558).

ZMQ channel architecture
ChannelPortServer socketClient socketRequest payloadReply payload
admin5556REP bind tcp://*:5556REQ connect tcp://<host>:5556Raw bytes (ping/pause/unpause/kill)Echoed admin response bytes
command5557REP bind tcp://*:5557REQ connect tcp://<host>:5557Python object list of command tuplesList of dispatched cmd_id values
status5558REP bind tcp://*:5558REQ connect tcp://<host>:5558Sentinel value 'STA'Latest full robot status dictionary

Full Command and Reply Chain

End-to-end flow from client command dispatch through transport framing and MCU reply decode.

Expanded communication flow from client to firmware
StepFromToProtocolDescription
1StretchBodyClient Command ChannelREQ/REP tcp://<host>:5557Client sends batched commands as [subsystem, method, cmd_id, args, kwargs].
2StretchBodyServerRobotServer._cb_command_dispatchIn-process dispatchServer receives command list and calls target subsystem methods via getattr dispatch.
3Arm/Lift/OmniBase/PowerPeriph APIStepper / PowerPeriph firmware wrappersPython method callsMethods queue or emit array('B') payloads where payload[0] is the RPC ID.
4Device classTransport.do_rpcBody transport APIDevice-level wrapper selects push/pull and blocking/nonblocking behavior.
5TransportTransportPySerial or TransportCSerialPython backend switchPython backend uses AioSerial handlers; C backend uses -> libtransport.so.
6Transaction handlerFraming layerHello Serial Transport v0/v1Payload chunks are framed and ACKed (v1 uses 58-byte data chunks).
7Framing layer byte stream + Modbus + 0x00 delimiterFrames append Modbus CRC, -encode data, and terminate packets with 0x00.
8Host USB deviceMCU endpoints serialBytes travel through /dev/hello-motor-* and /dev/hello-power-periph device paths.
9Firmware MCUHost transport callbackACK / RPC replyMCU returns framed ACK or reply payload (reply IDs are +1 from command IDs).
10RPC callbackDevice status/config structsPython unpackCallbacks decode payload bytes into board status, telemetry, and configuration data.
11StretchBodyClient Status ChannelREQ/REP tcp://<host>:5558Client sends status sentinel ('STA') to request latest aggregated robot status dict.
12StretchBodyClient Admin ChannelREQ/REP tcp://<host>:5556Admin commands (ping/pause/unpause/kill) are exchanged as raw byte strings.

Classes, Methods, and RPC Mapping