This document defines the Beatbox CAN protocol exchanged between main and peripheral modules.
Beatbox uses standard 11-bit CAN IDs.
| Bits | Size | Field | Meaning |
|---|---|---|---|
| 10..8 | 3 | PRIO | Arbitration priority class (0 highest) |
| 7..4 | 4 | MODULE | Target module for request, source module for response |
| 3..2 | 2 | TYPE | Message class and direction |
| 1..0 | 2 | CMD | Command index inside the selected TYPE namespace |
Once a module is selected by MODULE, the message meaning is described by 3 protocol fields: PRIO, TYPE, CMD (plus payload).
Payload is 0..8 bytes. RTR is not used.
CAN_ID = (PRIO << 8) | (MODULE << 4) | (TYPE << 2) | CMD
| PRIO | Class | Typical usage |
| PRIO | Class | Typical usage |
|---|---|---|
| 000 | P0 highest | Critical errors, safety urgent |
| 001 | P1 high | Control commands (start/stop/reset/reward) |
| 010 | P2 medium | Real-time events (nosepoke, touch, barrier edge) |
| 011 | P3 normal | Status and ACK traffic |
| 100 | P4 background | Telemetry / periodic reporting |
| 101..111 | Reserved | Future use |
| TYPE | Meaning |
|---|---|
| 00 | Common request |
| 01 | Common response |
| 10 | Module-specific request |
| 11 | Module-specific response |
| Module | Value |
|---|---|
| GENERIC | 0x0 |
| MAIN | 0x1 |
| FEEDER | 0x2 |
| NOSEPOKE | 0x3 |
| SCREEN_LEFT | 0x4 |
| SCREEN_RIGHT | 0x5 |
| LIGHTING | 0x6 |
| IR_BARRIER | 0x7 |
| BROADCAST target | 0xF |
No response may use MODULE=0xF.
CMD values are global in this namespace.
| TYPE | CMD | Name | Direction | Default PRIO | Payload |
|---|---|---|---|---|---|
| 00 | 00 | SCAN | Request | P3 | none |
| 01 | 00 | SCAN_REPLY | Response | P3 | status_code:uint8 |
| 00 | 01 | GET_STATUS | Request | P3 | none |
| 01 | 01 | STATUS | Response | P3 | status_code:uint8 |
| 01 | 10 | ERROR | Response | P0 | error_code:uint8 (+ optional module-specific context bytes) |
| 00 | 11 | RESET | Request | P1 | delay_ms:uint16 big-endian |
Modules may append context bytes after error_code. Receivers must tolerate an
ERROR payload longer than one byte. See section 4.1 for the feeder case.
Status values:
0: INIT1: IDLE2: ACTIVE3: ERROR
CMD is module-local in this namespace.
| TYPE | CMD | Name | Direction | Default PRIO | Payload |
|---|---|---|---|---|---|
| 10 | 00 | TOGGLE_CAN_LED | Request | P1 | none |
| 11 | 00 | CAN_LED_STATE | Response | P3 | state:uint8 (0 off, 1 on, 255 unknown) |
| 11 | 01 | USER_BUTTON_EVENT | Response | P2 | pressed:uint8 (1 pressed) |
| TYPE | CMD | Name | Direction | Default PRIO | Payload |
|---|---|---|---|---|---|
| 10 | 00 | GET_REWARD_STATUS | Request | P3 | none |
| 10 | 01 | REQUEST_REWARD | Request | P1 | none |
| 10 | 10 | REWARD_ON | Request | P1 | none |
| 10 | 11 | REWARD_OFF | Request | P1 | none |
| 11 | 00 | REWARD_STATUS | Response | P3 / P2 | state:uint8, attempts:uint8 |
REWARD_STATUS is the feeder's only module response. Its payload is two bytes:
| Byte | Meaning |
|---|---|
| 0 | state:uint8 = pellet presence, 1 pellet in the IR beam, 0 beam clear |
| 1 | attempts:uint8 = attempts made during the last autonomous delivery |
It is sent at P3 when it answers a request (GET_REWARD_STATUS, or the end of
a REQUEST_REWARD cycle), and at P2 when it reports a spontaneous pellet
presence change (see Pellet presence reporting).
All feeder requests must be addressed to MODULE=0x2; the feeder ignores
module requests received on BROADCAST, so a reward is never delivered by
accident.
REQUEST_REWARD and REWARD_ON are mutually exclusive: each is ignored while
the other is active.
One reward step is 1/25 of a revolution of the feeder disc. Pellet arrival is detected by an IR barrier interrupt local to the feeder module.
- Main sends
REQUEST_REWARD. The feeder switches toACTIVEand starts turning. A secondREQUEST_REWARDreceived while a delivery is running is ignored; pollGET_STATUSto observe progress. - The feeder turns 1/25 revolution, then waits up to 500 ms for the pellet.
- If no pellet is detected, it retries from step 2, up to 20 attempts total (about four fifths of a revolution of the disc).
- On detection the motor stops immediately, the module returns to
IDLEand sendsREWARD_STATUSatP3. Theattemptsbyte reports how many attempts were needed:1on first try, up to20.
If a pellet is already in the beam when REQUEST_REWARD arrives, the disc does
not turn: the feeder stays IDLE and answers REWARD_STATUS with state=1 and
attempts=0.
A reward therefore completes in about 500 ms in the nominal case, and can take
up to ~10 s before being reported as failed. Main must not assume a fixed
latency between REQUEST_REWARD and its REWARD_STATUS.
An attempts value consistently greater than 1 indicates a feeder running low
or a disc starting to jam, and is worth logging as a health metric.
REWARD_ON turns the disc continuously until REWARD_OFF, mirroring the V2
reward TTL line: main owns the timing and the retries. The module switches to
ACTIVE and runs the motor at a fifth of the nominal step rate.
REWARD_ONis idempotent: a second one while the motor runs is a no-op.REWARD_ONis ignored while an autonomous delivery is running.- The feeder stops by itself after 15 s without a
REWARD_OFF, so a lost link mid-delivery cannot spin the disc forever. Main's longest reward pulse must stay below that. REWARD_OFFalso acts as an emergency stop: it aborts an autonomousREQUEST_REWARDcycle in progress.
Neither command answers with a REWARD_STATUS of its own; the pellet that comes
out is reported by the presence events below.
The feeder publishes REWARD_STATUS at P2 (event priority) on every pellet
presence change, independently of what triggered it. Main sees both edges:
state=1is latched by the IR barrier interrupt and sent immediately, so a pellet transiting faster than the 10 ms poll period is never missed.state=0is sent once the beam has been continuously clear for 50 ms.
This works whether the barrier watches the chute (transit: 1 then 0 shortly
after) or the food well (presence: 0 only once the animal takes the pellet).
The attempts byte carries the count from the last autonomous delivery and is
unchanged by these events.
If the 20 attempts elapse without a pellet, the feeder sends the common ERROR
response (TYPE=01, CMD=10, P0) instead of a P3 REWARD_STATUS, and stays
in ERROR status until the next successful reward.
The error payload extends the generic error_code:uint8 form with the command
that failed and the number of attempts made:
| Byte | Meaning |
|---|---|
| 0 | error_code:uint8 = failing command, 0x01 for REQUEST_REWARD |
| 1 | attempts:uint8 = attempts made before giving up (20) |
No P3 REWARD_STATUS is emitted in this case. A new REQUEST_REWARD is
accepted while the module is in ERROR, so main can retry after refilling.
A cycle aborted by REWARD_OFF is silent: the module returns to IDLE without
an ERROR and without a REWARD_STATUS.
| TYPE | CMD | Name | Direction | Default PRIO | Payload |
|---|---|---|---|---|---|
| 10 | 00 | GET_BEAM_STATUS | Request | P3 | none |
| 11 | 00 | BEAM_STATUS | Response | P3 | beam:uint8 (0 clear, 1 broken) |
| 11 | 01 | BEAM_EVENT | Response | P2 | beam:uint8 (1 when poke event detected) |
Screen side is encoded by module ID, so payload has no side field.
| TYPE | CMD | Name | Direction | Default PRIO | Payload |
|---|---|---|---|---|---|
| 10 | 00 | DISPLAY_PATTERN | Request | P1 | pattern_id:uint8 |
| 11 | 00 | DISPLAY_PATTERN_ACK | Response | P3 | pattern_id:uint8 |
| 11 | 01 | TOUCH_EVENT | Response | P2 | touch:uint8 (1 touched) |
| TYPE | CMD | Name | Direction | Default PRIO | Payload |
|---|---|---|---|---|---|
| 10 | 00 | SET_DUTY | Request | P1 | white:uint8, red:uint8, ir:uint8 |
| 11 | 00 | SET_DUTY_ACK | Response | P3 | white:uint8, red:uint8, ir:uint8 |
| 10 | 01 | GET_DUTY | Request | P3 | none |
| 11 | 01 | DUTY_STATUS | Response | P3 | white:uint8, red:uint8, ir:uint8 |
| 10 | 10 | TURN_ON_GROUP | Request | P1 | group:uint8 (0 IR, 1 RED, 2 WHITE) |
| 10 | 11 | TURN_OFF | Request | P1 | optional group:uint8 (empty = all) |
| TYPE | CMD | Name | Direction | Default PRIO | Payload |
|---|---|---|---|---|---|
| 10 | 00 | GET_BARRIER_STATUS | Request | P3 | none |
| 11 | 00 | BARRIER_STATUS | Response | P3 | barrier:uint8 (0 clear, 1 blocked) |
| 11 | 01 | BARRIER_EVENT | Response | P2 | barrier:uint8 (1 on edge event) |
With PRIO in the top bits, arbitration follows functional urgency before module identity:
- lower
PRIOwins first, - then lower
MODULE, - then lower
TYPE, - then lower
CMD.
This avoids permanent dominance by low module IDs and matches the target policy: error > control > event > status/telemetry.
- Broadcast scan request (
P3,BROADCAST, common request,SCAN):- bits:
011 1111 00 00
- bits:
- Nosepoke event (
P2,NOSEPOKE, module response,BEAM_EVENT):- bits:
010 0011 11 01
- bits:
- Lighting set duty (
P1,LIGHTING, module request,SET_DUTY):- bits:
001 0110 10 00
- bits:
- Feeder reward request (
P1,FEEDER, module request,REQUEST_REWARD):- bits:
001 0010 10 01, ID0x129, no payload
- bits:
- Feeder reward delivered on the third attempt (
P3,FEEDER, module response,REWARD_STATUS):- bits:
011 0010 11 00, ID0x32C, payload01 03(pellet present, 3 attempts)
- bits:
- Feeder pellet taken from the well (
P2,FEEDER, module response,REWARD_STATUS):- bits:
010 0010 11 00, ID0x22C, payload00 03
- bits:
- Feeder delivery failure after 20 attempts (
P0,FEEDER, common response,ERROR):- bits:
000 0010 01 10, ID0x026, payload01 14
- bits:
This layout provides 2 command bits (CMD=0..3) per TYPE namespace.
If a module later needs more than 4 module-specific operations, use either:
- one
CMDvalue as a payload sub-opcode container, or - a protocol v2 based on 29-bit IDs.