Request

To send commands, use the Request datatype. When your request is processed the Ravas Redbox will send a Response.

A request has three parts: a message_id you choose yourself (it is echoed in the response), the type — the command — and a payload. The payload is a oneof, so exactly one field of it is set. The tables below list which payload belongs to which request type.

Basic requests

Most commands only need a scale index. A basic request is shown in the code (C) example below. In this example a Uint32_tag is sent to the Ravas RedBox.

Example

//Request type is defined in converted protobuf file from compiler
bool protocol_send_basic_request(Request_Type type, uint32_t val)
{
    Request request         = {};
    request.type            = type;
    request.which_payload   = Request_Uint32_tag;
    request.payload.Uint32  = val;

    return send_request(&request);
}

Scale requests

Request below can be send via a basic request as described above. As payload an Uint32_tag is filled in with the scale index (0).

Every one of these answers with a result. Anything other than OK means the scale refused the command and nothing changed.

Request	Payload	Description
`SET_ZERO`	scale_number (uint32)	The load on the scale right now becomes gross 0. Refused with `ZERO_OUT_OF_RANGE` if that load is outside the zero setting range
`SET_TARE`	scale_number (uint32)	Toggles the tare. Without an active tare, the gross weight on the scale right now becomes the tare, so net reads 0 and the scale switches to net mode. With a tare active, the tare is cleared and net reads the same as gross again
`SET_ZERO_OR_TARE`	scale_number (uint32)	One button for an operator: clears the weighed or manual tare if one is active, otherwise zeroes the scale, which also clears a tare preset — and tares instead when the load is too big to zero
`SET_SUM_WEIGHING_ADD`	scale_number (uint32)	Add current weight to the totalizing register
`SET_SUM_FINAL`	scale_number (uint32)	Finalize SUM and store to alibi memory
`SET_SUM_RESET`	scale_number (uint32)	Throw the running total away without closing it

Totalising

Totalising adds up several loads and then closes the batch off. Every weighing is written to the alibi memory as it is added, and the batch again when it is closed.

At most 99 weighings fit in one batch, and the total net weight has to fit the display, otherwise TOTALIZING_TOO_MUCH.
The scale has to return to zero between two additions, otherwise TOTALIZING_MUST_RETURN_TO_ZERO. The TotalizingResult in the live weight tells you when, through need_to_see_zero.
SET_SUM_FINAL answers with weight_ext whose net and gross hold the totals, and starts a fresh batch. Its total_update is not filled in. On an empty batch it answers TOTALIZING_ALREADY_FINALIZED.
SET_SUM_FINAL also prints a receipt when a Bluetooth printer is connected. ESP32 RedBoxes do not print receipts.
A failure to write the alibi memory does not stop totalising: the command still succeeds, and alibi_nr is 0.

Manual tare

Tare with a weight the operator typed in, instead of weighing it.

Request	Payload	Description
`SET_MANUAL_TARE`	`ManualTare`	Set manual tare value. Scale switches to net mode

ManualTare contains the scale number and the tare weight itself:

Example

//Request type is defined in converted protobuf file from compiler
bool protocol_send_manual_tare(uint32_t scale_index, float value)
{
    Request request                             = {};
    request.type                                = Request_Type_SET_MANUAL_TARE;
    request.which_payload                       = Request_manual_tare_tag;
    request.payload.manual_tare.scale_number    = scale_index;
    request.payload.manual_tare.preset_weight   = value;

    return send_request(&request);
}

Tare presets

Tare presets are a named list stored per scale, for containers that come back often. The requests below manage the list; the list itself is readable through the scale parameters TARE_PRESET_NAMES and TARE_PRESET_VALUES.

Request	Payload	Description
`CREATE_TARE_PRESET`	`CreateTarePreset`	Add a named tare to the list. Answers `VALUE_OUT_OF_RANGE` when the list is full
`UPDATE_TARE_PRESET`	`UpdateTarePreset`	Replace the weight and the name of one entry. Always send both
`DELETE_TARE_PRESET`	`DeleteTarePreset`	Remove one entry. The remaining entries move up, so indexes shift
`SET_PRESET_TARE`	`PresetTare`	Apply an entry from the list as the active tare. Index 0 is the manual tare

Payload message	Fields
`CreateTarePreset`	scale_number (uint32), tare_offset (float), name (string)
`UpdateTarePreset`	scale_number (uint32), tare_offset (float), name (string), preset_index (uint32)
`DeleteTarePreset`	scale_number (uint32), preset_index (uint32)
`PresetTare`	scale_number (uint32), preset_index (uint32)

Example

//Request type is defined in converted protobuf file from compiler
bool protocol_send_preset_tare(uint32_t scale_index, uint32_t preset_index)
{
    Request request                             = {};
    request.type                                = Request_Type_SET_PRESET_TARE;
    request.which_payload                       = Request_preset_tare_tag;
    request.payload.preset_tare.scale_number    = scale_index;
    request.payload.preset_tare.preset_index    = preset_index;

    return send_request(&request);
}

Weighing result requests

Request	Payload	Description
`GET_STATIC_WEIGHT_WITH_ALIBI`	scale_number (uint32)	Take one static weight reading and store it in the alibi memory. Answers with `weight_ext`, or with `result` on an error

Note

Use GET_STATIC_WEIGHT_WITH_ALIBI — not a value copied out of the live feed — whenever the reading has to become part of the alibi record. The response carries the alibi_nr it was stored under.

For a continuous stream of weights, subscribe instead.

Alibi memory requests

Request	Payload	Description
`GET_ALIBI_ENTRY`	alibi number (uint32)	Read one record by its alibi number. Answers with `alibi_entry`
`GET_ALIBI_LIST`	none	Answers `result` OK, sends every record as an `alibi_entry`, oldest first, and ends with `result` `NO_MORE_DATA`

The responses that follow the OK of GET_ALIBI_LIST carry message_id 0.

Records are retained for at least a configured age before the oldest are overwritten. The number of stored records is readable as the system parameter ALIBI_COUNT.

Parameter requests

Request	Payload	Description
`GET_PARAMETER`	`ParameterReference` (get_parameter)	Read one parameter. Answers with `parameter`
`SET_PARAMETER`	`SetParameter` (set_parameter)	Write one parameter

Read-only parameters and parameters above your access level are refused with PARAMETER_CHANGE_NOT_ALLOWED_READ_ONLY or USER_LEVEL_TOO_LOW. See Parameter management for code examples and the full parameter lists.

WiFi requests

Scanning is asynchronous: start a scan, wait for the scan_done response, then ask for the list.

Note

scan_done is only sent to connections that have SUBSCRIBE_PARAMETERS active. Subscribe before you start a scan, and use a timeout: when a full scan cannot start, no result is sent at all.

Request	Payload	Description
`WIFI_START_QUICK_SCAN`	none	Scan only the channel the radio is on now. Faster, misses networks on other channels
`WIFI_START_FULL_SCAN`	none	Scan every channel
`GET_WIFI_APS`	none	Fetch the last scan: `result` OK, then one `scan_result` per network found
`WIFI_CONNECT`	`WifiCredentials`	Join a network. The credentials are stored once the connection succeeds
`WIFI_DISCONNECT`	none	Drop the current connection, keeping the stored credentials
`WIFI_FORGET`	none	Clear the stored credentials. An existing connection stays up
`WIFI_CLEAR_MESSAGE`	none	Acknowledge the last connection state, so `STA_CONNECT_STATE` reads clean again

WifiCredentials contains ssid (string), password (string), min_auth_mode (Wifi_AuthMode) and channel (uint32).

Warning

WIFI_CONNECT answers OK as soon as it accepts the request, before it tries to connect. The outcome shows in the WiFi parameters STA_CONNECTED and STA_CONNECT_STATE.

sequenceDiagram
    Client->>RedBox: SUBSCRIBE_PARAMETERS
    RedBox-->>Client: result (OK), then every parameter once
    Client->>RedBox: WIFI_START_FULL_SCAN
    RedBox-->>Client: result (OK)
    RedBox->>Client: scan_done
    Client->>RedBox: GET_WIFI_APS
    RedBox-->>Client: result (OK)
    RedBox-->>Client: scan_result (network 1)
    RedBox-->>Client: scan_result (network 2)

Other requests

Request	Payload	Description
`CALIBRATE_ANTENNA`	none	Erase the WiFi and Bluetooth radio calibration. The radio recalibrates at the next restart