krabby-firmware 0.2.13

Python SDK for Krabby MCU (e.g. Arduino) communication

Krabby-Uno Task 2: Six-Axis Leg Controller

Overview

This firmware drives a full leg pair (Left & Right) consisting of 6 Motors.

Prerequisites

• Hardware:
  • Arduino Mega 2560
  • 6x BTS7960 43A H-Bridge Drivers
  • 12x Resistors (10kΩ) for Current Sense protection
  • 12V Power Supply
• Software:
  • Python 3
  • Libraries: pip install pyserial keyboard
  • Arduino IDE

---

1. Hardware Wiring (Rev 3 — Krabby Uno v0.2)

Polarity Note:

• RPWM / R_EN = Right (Extend/Forward).
• LPWM / L_EN = Left (Retract/Reverse).

Board	Joint	PWM (R, L)	EN	Potentiometer	Current Sense	HallA
FL	Yaw (LHY)	D2, D3	D22	A0	A6	D50
	Hip (LHL)	D4, D5	D24	A1	A7	D51
	Knee (LKL)	D6, D7	D26	A2	A8	D52
FR	Yaw (RHY)	D8, D9	D23	A3	A9	A12
	Hip (RHL)	D10, D11	D25	A4	A10	A13
	Knee (RKL)	D12, D13	D27	A5	A11	A14

Note: Ensure all Enable (EN) pins are connected and driven HIGH when driving, otherwise calibration will get 'lost' as it will not know where joint positions are.

---

2. Installation

2.1 Serial RX buffer (leader board, 3-board setup)

When using the leader board that forwards telemetry from left/right followers, the default 64-byte serial RX buffer can overflow and drop bytes (corrupt or missing actuators in telemetry). Use a 256-byte RX buffer for Serial2/Serial3 on the leader.

You do not flash the core separately. The Arduino “core” is just C++ source that is compiled with your sketch into a single firmware image. Change the buffer size, then build and upload as usual.

Arduino IDE

• Option A – One-time edit (survives until you update the AVR board package):
  Open the core file (path similar to):

  • Windows: %LOCALAPPDATA%\Arduino15\packages\arduino\hardware\avr\1.8.7\cores\arduino\HardwareSerial.h
  • macOS: ~/Library/Arduino15/packages/arduino/hardware/avr/1.8.7/cores/arduino/HardwareSerial.h
    Find the block that sets SERIAL_RX_BUFFER_SIZE (e.g. #define SERIAL_RX_BUFFER_SIZE 64) and change 64 to 256. Save. Then compile and upload your sketch as usual.

• Option B – Build flag via platform override:
  In the same avr package folder (e.g. .../packages/arduino/hardware/avr/1.8.7/), create or edit platform.local.txt and add:

  compiler.c.extra_flags=-DSERIAL_RX_BUFFER_SIZE=256
  compiler.cpp.extra_flags=-DSERIAL_RX_BUFFER_SIZE=256
  

  so the define is applied when the core and your sketch are compiled. Then build/upload as usual.

PlatformIO

In platformio.ini for the board that acts as the leader, add:

build_flags = -DSERIAL_RX_BUFFER_SIZE=256

Then build and upload. No core file edit needed.

Follower-only boards do not need this change; only the board that runs forwardFullLines (the leader on USB) benefits from the larger buffer.

2.2 Telemetry format (wire protocol)

Telemetry is sent as newline-terminated lines over serial. The Python side parses each line into a dict of joint id → values using JointTelemetry in interfaces/joint_telemetry.py.

• Line format: <ROLE>; <name> <pos> <pot> <current> <enL> <enR> <pwmL> <pwmR> <saf>; <name> ...; ...
• Role prefix: One of FRONT, UNKNOWN, LEFT, RIGHT (no semicolon inside the role).
• Segment format: Each joint segment is 9 space-separated values: joint name, position (0–1), pot raw, current raw, enable L/R, PWM L/R, safety.
• Example: FRONT; FLHY 0.723 740 694 0 0 0 0 0;FLHL 0.723 740 691 ...

On the Arduino side, telemetry is built in telemetry_manager.h (struct JointTelemetry, appendTo()). The old standalone joint_telemetry.h was removed; all telemetry formatting and collection lives in telemetry_manager.h and actuator_manager.h.

2.3 Pin revisions (KRABBY_PIN_REV)

Wiring is selected at compile time in arduino/board_pins.h (#define KRABBY_PIN_REV, default 2). Rev 3 matches MOTOR_HEADER_PINOUT.md.

	Rev 3 (default, Uno v0.2)	Rev 2 (Uno v0.1)	Rev 1 (original)
PWM	D2-D13	D2-D13	D2-D13
FL EN (LHY / LHL / LKL)	D22 / D24 / D26	D22 / D23 / D24	D22 / D23 / D24
FR EN (RHY / RHL / RKL)	D23 / D25 / D27	D28 / D26 / D27	D28 / D26 / D27
HallA1-6	D50, D51, D52, A12, A13, A14 (PCINT0+2)	none	D37, D36, D35, D32, D33, D34 (PCINT1)

• Arduino IDE: open firmware/arduino/arduino.ino, set Board → Arduino Mega 2560, choose the correct Port, set KRABBY_PIN_REV in board_pins.h if needed, then Upload. The serial monitor at 115200 baud should show PINS_REV3_UNO_V02 (or the matching label) after reset.
• Make + arduino-cli: install arduino-cli and GNU Make. On Windows: winget install GnuWin32.Make then add C:\Program Files (x86)\GnuWin32\bin to your PATH. Put arduino-cli on your PATH (or set ARDUINO_CLI). Install pyserial for port auto-detect: pip install -r firmware/requirements.txt. From krabby-research:
  • make -C firmware upload-firmware — auto-detects serial port via firmware/mcu_port.default_port(). Pass PORT=COM5 (or /dev/ttyACM0) to override.
  • Other revisions: make -C firmware upload-firmware PIN_REV=1 (or PIN_REV=2).
  • Compile only: make -C firmware compile-firmware.
  • See firmware/Makefile for ARDUINO_CLI, FQBN, PIN_REV.

Flash each Mega with the image that matches that board’s wiring. All three boards use the same sketch; role is elected at runtime.

2.4 Python SDK

1. From krabby-research, install dependencies: pip install -r firmware/requirements.txt.
2. Ensure firmware/interfaces/ is importable (e.g. run python -m firmware from krabby-research as in §3).

---

3. Usage Guide

Run the interactive MCU menu from the krabby-research directory:

# On Linux/Mac, you may need sudo for keyboard access
python -m firmware

For troubleshooting (verbose telemetry):

python -m firmware --debug

EEPROM address layout

Address	Size	Purpose
0–25	26 bytes	CalData struct — calibration min/max for 6 actuators + magic word (0xDEADBEEF)
26–31	6 bytes	Reserved (alignment gap)
32	1 byte	Role magic sentinel (0xAB) — written once after first successful role election
33	1 byte	BoardRole value: 1=FRONT, 2=LEFT, 3=RIGHT

The role bytes survive power cycles. On each boot, the board prints ROLE_HINT: LEFT/RIGHT/FRONT immediately before the 3-second role-election window. krabby-firmware show reads this hint so follower boards can be labeled correctly even when probed individually (when they would otherwise appear as ROLE_UNKNOWN and show as "primary").

Role bytes are only written when a valid role is elected (FRONT, LEFT, or RIGHT). A board that times out as ROLE_UNKNOWN does not update EEPROM, preserving the last valid role.

Feature 1: Auto-Calibration (Run Once)

The robot now calibrates itself automatically and saves limits to EEPROM.

• Select Option 2 (Auto-Calibrate) in the menu.
• Stand Back: The robot will perform the safety sequence:
  • Yaw Left -> Yaw Right -> Hip Up -> Knee Out -> Knee In -> Hip Down.
• Result: Limits are saved. You do not need to repeat this after rebooting.

Feature 2: Manual Jog Mode

• Select Option 3 (Jog Mode).
• Type the joint name (e.g., LHY or LKL).
• Hold 'W' to Extend, Hold 'S' to Retract.
• Release keys to stop immediately.

Feature 3: Neutral Pose

• Select Option 1.
• Robot moves all joints to center (0.5). Useful to verify calibration accuracy.

---

4. Firmware Store (krabby-firmware-public)

Built firmware lives in a public S3 bucket. CI publishes a new build on every push to mainline or release/*.

4.1 Bucket layout

s3://krabby-firmware-public/
  index.json                               ← all branches, latest build per branch
  <branch>/latest.json                     ← pointer to the most recent build on <branch>
  <branch>/<YYYYMMDD-HHMMSS-<sha7>>/
    firmware.hex                           ← compiled Arduino HEX
    manifest.json                          ← branch, commit, timestamp, board FQBN, VER string

<branch> mirrors the Git branch name (mainline, release/0.2.0, etc.).

manifest.json fields: schema_version, branch, commit, commit_date, build_timestamp, board_fqbn, ver_string, hex_filename.

4.2 V protocol

Send V\n on the main serial (115200 baud). The leader board collects replies from all three boards and responds with a single line:

VER <versions> <branches> <commits>

Each field is primary|left|right pipe-delimited. Example:

VER 0.2.0|0.2.0|0.2.0 release/0.2.0|release/0.2.0|release/0.2.0 abc1234|def5678|ghi9012

If a follower board is missing, its slot contains -.

4.3 Three-board update procedure

# 1. One-time host setup (udev rules, dialout group, flash tools)
sudo krabby-firmware install

# 2. Check attached boards and available S3 builds
krabby-firmware show

# 3. Flash all three boards in turn (replug USB between boards)
krabby-firmware update                        # latest release/* build, auto-detects port
krabby-firmware update release/0.2.0          # specific branch
krabby-firmware update /dev/ttyACM1           # specific port, latest release
krabby-firmware update release/0.2.0 /dev/ttyACM2  # specific branch + port

Downloaded HEX files are cached under ~/.cache/krabby-firmware/<branch>/<sha7>/firmware.hex and reused on subsequent calls.