Subscriptions

General

Subscribe

The communication protocol allows for subscribing to specific scale events. The corresponding information will then be sent when an event occurs. The device keeps sending until you unsubscribe or disconnect.

Warning

Once a subscription is activated, the protocol can no longer be regarded as purely synchronous, since Response packets can be sent at any time. Make use of the message_id field to track Response/Request pairs.

The following events are available:

Info

Clicking on the response field tag will redirect you to the page where you can find more information about the selected response.

Event	Payload	Response field	Description
SUBSCRIBE_WEIGHT	Scale number (uint32)	WeighingResult_ext, wim_result	Live weight, sent on every display update, and completed weigh-in-motion measurements
SUBSCRIBE_PARAMETERS	Skip names (bool)	ParameterDescription, scan_done	All parameters once, then every change, and the end of a WiFi scan
SUBSCRIBE_PARAMETER	ParameterReference	ParameterDescription	One parameter only
SUBSCRIBE_POWER_EVENTS	None	PowerEvent	Get updates over battery/ sleep modes
SUBSCRIBE_PRINTER	None	PrinterEvent	Get status updates from the printer

Parameter subscriptions

SUBSCRIBE_PARAMETERS first sends every parameter once, as individual Response messages with a parameter payload. From that point on, an updated value is sent whenever a parameter changes.

Its payload is a bool: set it to true to leave human_readable_name out of the messages, which keeps the initial burst much smaller when your client already knows the names.

Note

Not every parameter is a setting. Some only report a status — the readout of the temperature sensor, for example. Those are not writable, but arrive through this same system as a parameter update.

The same subscription also delivers scan_done at the end of a WiFi scan.

SUBSCRIBE_PARAMETER (singular) takes a ParameterReference — a page id plus a parameter id — and watches that one parameter. Cheaper if you only want to follow a single value.

Weigh in motion

SUBSCRIBE_WEIGHT also reports one wim_result per drive-through: a finished measurement, next to the live weight_ext feed in which single_measurement_progress tracks the measurement as it runs.

Unsubscribe

Event	Payload
UNSUBSCRIBE_WEIGHT	Scale number (uint32)
UNSUBSCRIBE_PARAMETERS	None
UNSUBSCRIBE_PARAMETER	ParameterReference
UNSUBSCRIBE_POWER_EVENTS	None
UNSUBSCRIBE_PRINTER	None

Sequence diagram

The following diagram describes the sequence when subscribing to event X and event Y:

sequenceDiagram
    Client->>RedBox: Request subscription X
    RedBox-->>Client: Response status
    Client->>RedBox: Request subscription Y
    RedBox-->>Client: Response status
    loop Every x ms
        RedBox->>Client: Response subscription X
        RedBox->>Client: Response subscription Y
    end
    Client->>RedBox: Request unsubscription X
    RedBox-->>Client: Response status
    Client->>RedBox: Request unsubscription Y
    RedBox-->>Client: Response status

Sending subscription example

The code example below shows a client that is subscribed to the weight updates and power event from a Ravas RedBox.

Example

See also: protocol_send_basic_request() for an example how to send the request.

#define DEFAULT_SCALE_INDEX 0

void protocol_send_subs()
{
    protocol_send_basic_request(Request_Type_SUBSCRIBE_WEIGHT,          DEFAULT_SCALE_INDEX);
    protocol_send_basic_request(Request_Type_SUBSCRIBE_POWER_EVENTS,    DEFAULT_SCALE_INDEX);
}