Packet Payloads

This document defines the CBOR payload structure for each Fusain message type. For packet framing, see Packet Format. For the canonical schema, see fusain.cddl.

All payloads are CBOR maps with integer keys. Optional fields (marked with ?) may be omitted.

Message Types

Configuration Commands

Type	Name	Description
0x10	MOTOR_CONFIG	Configure motor controller parameters
0x11	PUMP_CONFIG	Configure pump controller parameters
0x12	TEMPERATURE_CONFIG	Configure temperature controller parameters
0x13	GLOW_CONFIG	Configure glow plug parameters
0x14	DATA_SUBSCRIPTION	Subscribe to data from appliance
0x15	DATA_UNSUBSCRIBE	Unsubscribe from appliance data
0x16	TELEMETRY_CONFIG	Enable/disable telemetry broadcasts
0x17	TIMEOUT_CONFIG	Configure communication timeout
0x18-0x1E	Reserved	Reserved for future configuration commands
0x1F	DISCOVERY_REQUEST	Request device capabilities

Control Commands

Type	Name	Description
0x20	STATE_COMMAND	Set system mode/state
0x21	MOTOR_COMMAND	Set motor RPM
0x22	PUMP_COMMAND	Set pump rate
0x23	GLOW_COMMAND	Control glow plug
0x24	TEMPERATURE_COMMAND	Temperature controller control
0x25	SEND_TELEMETRY	Request telemetry data (polling mode)
0x26-0x2E	Reserved	Reserved for future control commands
0x2F	PING_REQUEST	Heartbeat/connectivity check

Telemetry Data

Type	Name	Description
0x30	STATE_DATA	System state and status
0x31	MOTOR_DATA	Motor telemetry
0x32	PUMP_DATA	Pump status and events
0x33	GLOW_DATA	Glow plug status
0x34	TEMPERATURE_DATA	Temperature readings
0x35	DEVICE_ANNOUNCE	Device capabilities announcement
0x36-0x3E	Reserved	Reserved for future telemetry messages
0x3F	PING_RESPONSE	Heartbeat response

Error Messages

Type	Name	Description
0xE0	ERROR_INVALID_CMD	Command validation failed
0xE1	ERROR_STATE_REJECT	Command rejected by state machine
0xE2-0xEF	Reserved	Reserved for future error messages

Configuration Commands

Configuration commands are sent from controllers to appliances to set persistent parameters. Message types range from 0x10 to 0x1F.

MOTOR_CONFIG

Message Type: 0x10

Behavior: MOTOR_CONFIG

Configure motor controller parameters.

Payload Fields

Key	Field	Type	Description
0	motor	int	Motor index (negative values reserved)
1 (?)	pwm_period	uint	PWM period in nanoseconds (optional)
2 (?)	pid_kp	float	Proportional gain (optional)
3 (?)	pid_ki	float	Integral gain (optional)
4 (?)	pid_kd	float	Derivative gain (optional)
5 (?)	max_rpm	int	Maximum RPM (optional)
6 (?)	min_rpm	int	Minimum stable RPM (optional)
7 (?)	min_pwm_duty	uint	Minimum PWM pulse width in nanoseconds (optional)

PUMP_CONFIG

Message Type: 0x11

Behavior: PUMP_CONFIG

Configure fuel pump parameters.

Payload Fields

Key	Field	Type	Description
0	pump	int	Pump index (negative values reserved)
1 (?)	pulse_ms	uint	Solenoid pulse duration in milliseconds (optional)
2 (?)	recovery_ms	uint	Recovery time after pulse in milliseconds (optional)

TEMPERATURE_CONFIG

Message Type: 0x12

Behavior: TEMPERATURE_CONFIG

Configure temperature controller parameters.

Payload Fields

Key	Field	Type	Description
0	thermometer	int	Temperature sensor index (negative values reserved)
1 (?)	pid_kp	float	Proportional gain (optional)
2 (?)	pid_ki	float	Integral gain (optional)
3 (?)	pid_kd	float	Derivative gain (optional)

GLOW_CONFIG

Message Type: 0x13

Behavior: GLOW_CONFIG

Configure glow plug parameters.

Payload Fields

Key	Field	Type	Description
0	glow	int	Glow plug index (negative values reserved)
1 (?)	max_duration	uint	Maximum glow duration in milliseconds (optional)

DATA_SUBSCRIPTION

Message Type: 0x14

Behavior: DATA_SUBSCRIPTION

Subscribe to data from an appliance (controller-to-controller routing).

Payload Fields

Key	Field	Type	Description
0	appliance_address	uint	64-bit address of the appliance to subscribe to

DATA_UNSUBSCRIBE

Message Type: 0x15

Behavior: DATA_UNSUBSCRIBE

Remove a data subscription.

Payload Fields

Key	Field	Type	Description
0	appliance_address	uint	64-bit address of the appliance to unsubscribe from

TELEMETRY_CONFIG

Message Type: 0x16

Behavior: TELEMETRY_CONFIG

Enable or disable periodic telemetry broadcasts.

Payload Fields

Key	Field	Type	Description
0	enabled	bool	Telemetry broadcast enabled
1	interval_ms	uint	Broadcast interval in milliseconds (0 = polling mode)

TIMEOUT_CONFIG

Message Type: 0x17

Behavior: TIMEOUT_CONFIG

Configure communication timeout behavior.

Payload Fields

Key	Field	Type	Description
0	enabled	bool	Timeout enabled
1	timeout_ms	uint	Timeout interval in milliseconds (5000-60000)

DISCOVERY_REQUEST

Message Type: 0x1F

Behavior: DISCOVERY_REQUEST

Request device capabilities from all appliances. Appliances respond with DEVICE_ANNOUNCE.

Payload: nil (empty)

Control Commands

Control commands are sent from controllers to appliances for real-time operational control. Message types range from 0x20 to 0x2F.

STATE_COMMAND

Message Type: 0x20

Behavior: STATE_COMMAND

Set system operating mode.

Payload Fields

Key	Field	Type	Description
0	mode	uint	Operating mode (see values below)
1 (?)	argument	int	Mode-specific parameter (optional)

Mode Values

Value	Mode	Argument
0	IDLE	Ignored
1	FAN	Target RPM
2	HEAT	Pump rate (milliseconds)
255	EMERGENCY	Ignored

MOTOR_COMMAND

Message Type: 0x21

Behavior: MOTOR_COMMAND

Set motor speed.

Payload Fields

Key	Field	Type	Description
0	motor	int	Motor index (negative values reserved)
1	rpm	int	Target speed (0 = stop)

PUMP_COMMAND

Message Type: 0x22

Behavior: PUMP_COMMAND

Set fuel pump rate.

Payload Fields

Key	Field	Type	Description
0	pump	int	Pump index (negative values reserved)
1	rate_ms	int	Pulse interval in milliseconds (0 = stop)

GLOW_COMMAND

Message Type: 0x23

Behavior: GLOW_COMMAND

Control glow plug.

Payload Fields

Key	Field	Type	Description
0	glow	int	Glow plug index (negative values reserved)
1	duration	int	Burn duration in milliseconds (0 = extinguish)

TEMPERATURE_COMMAND

Message Type: 0x24

Behavior: TEMPERATURE_COMMAND

Configure temperature controller operation.

Payload Fields

Key	Field	Type	Description
0	thermometer	int	Temperature sensor index (negative values reserved)
1	type	uint	Command type (see values below)
2 (?)	motor_index	uint	Motor to control (WATCH_MOTOR only, optional)
3 (?)	target_temperature	float	Target temperature in °C (SET_TARGET_TEMPERATURE only, optional)

Command Type Values

Value	Type	Description
0	WATCH_MOTOR	Associate temperature sensor with a motor
1	UNWATCH_MOTOR	Remove motor association
2	ENABLE_RPM_CONTROL	Enable automatic RPM adjustment
3	DISABLE_RPM_CONTROL	Disable automatic RPM adjustment
4	SET_TARGET_TEMPERATURE	Set target temperature for PID control

SEND_TELEMETRY

Message Type: 0x25

Behavior: SEND_TELEMETRY

Request specific telemetry data (polling mode).

Payload Fields

Key	Field	Type	Description
0	telemetry_type	uint	Telemetry type (see values below)
1 (?)	index	uint	Peripheral index (0xFFFFFFFF = all, optional)

Telemetry Type Values

Value	Type
0	STATE
1	MOTOR
2	TEMPERATURE
3	PUMP
4	GLOW

PING_REQUEST

Message Type: 0x2F

Behavior: PING_REQUEST

Connectivity check and timeout reset. Appliances respond with PING_RESPONSE.

Payload: nil (empty)

Telemetry Data

Telemetry messages are sent from appliances to controllers. Message types range from 0x30 to 0x3F.

STATE_DATA

Message Type: 0x30

Behavior: STATE_DATA

System state and error status.

Payload Fields

Key	Field	Type	Description
0	error	bool	Error flag (true if error occurred)
1	code	uint	Error code (see values below)
2	state	uint	Current state (see values below)
3	timestamp	uint	Time since boot in milliseconds

State Values

See Burn Cycle for operational details.

Value	State	Description
0	INITIALIZING	System startup in progress
1	IDLE	Ready for operation
2	BLOWING	Fan running without combustion
3	PREHEAT	Glow plug warming
4	PREHEAT_STAGE_2	Combustion starting, not yet stable
5	HEATING	Normal combustion active
6	COOLING	Cooldown sequence in progress
7	ERROR	Fault detected
8	E_STOP	Emergency stop active

Error Code Values

Value	Code	Description
0	NONE	No error
1	OVERHEAT	Temperature exceeded safety limit
2	SENSOR_FAULT	Temperature sensor failure
3	IGNITION_FAIL	Failed to reach ignition temperature
4	FLAME_OUT	Temperature dropped during heating
5	MOTOR_STALL	Motor RPM below threshold
6	PUMP_FAULT	Pump operation failure
7	COMMANDED_ESTOP	Emergency stop commanded

MOTOR_DATA

Message Type: 0x31

Behavior: MOTOR_DATA

Motor telemetry.

Payload Fields

Key	Field	Type	Description
0	motor	int	Motor index (negative values reserved)
1	timestamp	uint	Time since boot in milliseconds
2	rpm	int	Current measured speed
3	target	int	Target speed setpoint
4 (?)	max_rpm	int	Maximum achievable speed (optional)
5 (?)	min_rpm	int	Minimum stable speed (optional)
6 (?)	pwm	uint	Current PWM pulse width in nanoseconds (optional)
7 (?)	pwm_max	uint	PWM period in nanoseconds (optional)

PUMP_DATA

Message Type: 0x32

Behavior: PUMP_DATA

Fuel pump status and events.

Payload Fields

Key	Field	Type	Description
0	pump	int	Pump index (negative values reserved)
1	timestamp	uint	Event timestamp since boot in milliseconds
2	type	uint	Event type (see values below)
3 (?)	rate	int	Current pump rate in milliseconds (optional)

Event Type Values

Value	Type	Description
0	INITIALIZING	Pump controller starting up
1	READY	Pump ready for operation
2	ERROR	Pump fault detected
3	CYCLE_START	Beginning of a pump cycle
4	PULSE_END	Solenoid pulse completed
5	CYCLE_END	Recovery period completed

GLOW_DATA

Message Type: 0x33

Behavior: GLOW_DATA

Glow plug status.

Payload Fields

Key	Field	Type	Description
0	glow	int	Glow plug index (negative values reserved)
1	timestamp	uint	Status timestamp since boot in milliseconds
2	lit	bool	Glow state (true = lit, false = off)

TEMPERATURE_DATA

Message Type: 0x34

Behavior: TEMPERATURE_DATA

Temperature readings and PID status.

Payload Fields

Key	Field	Type	Description
0	thermometer	int	Sensor index (negative values reserved)
1	timestamp	uint	Reading timestamp since boot in milliseconds
2	reading	float	Current temperature in °C
3 (?)	temperature_rpm_control	bool	PID control active (optional)
4 (?)	watched_motor	int	Motor being controlled (optional)
5 (?)	target_temperature	float	Target temperature in °C (optional)

DEVICE_ANNOUNCE

Message Type: 0x35

Behavior: DEVICE_ANNOUNCE

Device capabilities (response to DISCOVERY_REQUEST).

Payload Fields

Key	Field	Type	Description
0	motor_count	uint	Number of motors
1	thermometer_count	uint	Number of temperature sensors
2	pump_count	uint	Number of pumps
3	glow_count	uint	Number of glow plugs

End-of-Discovery Marker

Routers send a special DEVICE_ANNOUNCE to mark the end of discovery:

• ADDRESS field: Stateless address (0xFFFFFFFFFFFFFFFF)

• All capability fields (motor_count, thermometer_count, pump_count, glow_count): 0

This packet indicates discovery is complete. It is the ONLY DEVICE_ANNOUNCE sent when no appliances are available. See Session Initiation for details.

PING_RESPONSE

Message Type: 0x3F

Behavior: PING_RESPONSE

Heartbeat response to PING_REQUEST.

Payload Fields

Key	Field	Type	Description
0	uptime_ms	uint	System uptime in milliseconds

Error Messages

Error messages are sent from appliances to controllers when commands fail. Message types range from 0xE0 to 0xEF.

ERROR_INVALID_CMD

Message Type: 0xE0

Behavior: ERROR_INVALID_CMD

Command validation failed.

Payload Fields

Key	Field	Type	Description
0	error_code	int	Error category (1 = invalid parameter, 2 = invalid index)
1 (optional)	rejected_field	uint	CBOR key of the field that failed validation
2 (optional)	constraint	uint	Constraint violation type (see values below)

Error Code Values

Value	Description
1	Invalid parameter value (out of range, NaN, etc.)
2	Invalid device index (motor, pump, or sensor does not exist)

Constraint Values

Value	Name	Description
0	UNSPECIFIED	No specific constraint (backward compatible)
1	VALUE_TOO_LOW	Value below minimum allowed
2	VALUE_TOO_HIGH	Value above maximum allowed
3	VALUE_INVALID	Value is NaN, Infinity, or otherwise invalid
4	VALUE_CONFLICT	Value conflicts with another field
5	INDEX_NOT_FOUND	Device index does not exist
6	FIELD_REQUIRED	Required field is missing
7	TYPE_MISMATCH	Field has wrong CBOR type
8	OPERATION_BLOCKED	Operation not allowed in current context
9	VALUE_IN_GAP	Value in invalid gap (e.g., rpm between 1 and min_rpm-1)

ERROR_STATE_REJECT

Message Type: 0xE1

Behavior: ERROR_STATE_REJECT

Command rejected by state machine.

Payload Fields

Key	Field	Type	Description
0	error_code	int	State that rejected the command
1 (optional)	rejection_reason	uint	Why the state rejected the command (see values below)

Rejection Reason Values

Value	Name	Description
0	UNSPECIFIED	No specific reason (backward compatible)
1	RESOURCE_CONTROLLED	Resource controlled by state machine
2	INVALID_IN_STATE	Operation not valid in current state
3	TRANSITION_BLOCKED	State transition not allowed (reserved)