Harp ESP32 Behaviour Box

Firmware for an ESP32-S3 Harp device that combines an onboard status RGB LED, a servo-driven sliding door, and a four-channel load-cell localizer. Harp communication uses TCP or native USB CDC, and the board can generate/repeat the Harp synchronization clock.

This repository is an application of harp.core.esp32.

Device summary

Item	Value
Target	ESP32-S3
Device name / tag	Behaviour Box / BBox
WhoAmI	1
Hardware version	1.0
Firmware version	0.1
Host transport	TCP or native USB CDC
Synchronization	UART1, RX GPIO4, TX GPIO5; generator capable and selected by default
App register range	36–46

Functionality

• Status LED: addressable RGB LED with off, on, automatic, blink, and fault modes.
• Door: percentage-position command with speed-limited motion and a completion event.
• Localizer: four HX711 load-cell channels, tare/calibration, total weight, and two-dimensional center of pressure.
• Networking: the core's optional Wi-Fi/TCP client is available through registers 32–35.
• Synchronization: the default configuration generates Harp clock frames and exposes hardware timestamps.

Register overview

Address	Register	Access	Purpose
36	STATUS_LED_MODE	R/W	off/on/auto/blink/fault mode
37–39	STATUS_LED_R/G/B	R/W	RGB color components
40	DOOR_POSITION	R/W	requested/reported travel, percent
41	DOOR_SPEED	R/W	linear speed, mm/s
42	LOCALIZER_CONFIG	R/W	enable, streams, and no-weight policy
43	LOCALIZER_POSITION	R	center of pressure [x, y], mm
44	LOCALIZER_WEIGHT	R	total weight, g
45	LOCALIZER_MIN_WEIGHT	R/W	minimum valid total weight, g
46	LOCALIZER_FILTER_ALPHA	R/W	requested filter coefficient

See the complete register map. Addresses 32–35 belong to the core network extension and must not be used as application registers.

Hardware

The checked-in defaults use:

Device	GPIOs / configuration
NeoPixel	GPIO48
Door servo	GPIO14, 50 Hz
HX711 shared clock	GPIO3
HX711 data	GPIO15, 16, 17, 18
Sync	UART1 RX4/TX5

The load-cell platform is modeled as 300 × 300 mm. Review the channel-to-corner mapping and perform a real calibration before relying on position or weight. See Hardware and Localizer and calibration.

Build

ESP-IDF 6 or later is required. Check requirements are configured in main/idf_component.yml with a local core copy:

dependencies:
  harp_core_esp32:
    path: ../../harp.core.esp32

or the Git repository:

dependencies:
  harp_core_esp32:
    git: https://github.com/barbaLab/harp.core.esp32.git

Then build with:

idf.py set-target esp32s3
idf.py build
idf.py flash

The current devcontainer bind-mount is machine-specific and must be replaced or removed on another workstation.

Runtime model

The Harp task runs on CPU 0 at high priority. Application modules run on CPU 1. At startup, the localizer initializes, waits, tares, and performs a hard-coded single-point calibration before Harp communication is initialized; this adds about six seconds and must be reviewed for production hardware.

The door accepts a target and performs movement asynchronously. A completion EVENT is emitted on address 40. The localizer can emit position and weight events according to its configuration bits.

Current limitations

• The checked-in host test scripts use obsolete register addresses and payloads. Do not run them unchanged; some writes target the network registers. Most tests will eventually be moved to a dedicated repository.
• The filter calculation is currently overwritten by the unfiltered center-of-pressure result, so alpha has no observable effect.
• The ROI configuration bit is reserved/TODO and has no implementation.
• Registers marked non-volatile in this application are not persisted by the current ESP32 core.
• Repeated Harp resets should be tested: several modules create tasks/timers during reset without explicit teardown.