Simulator
The RedBox simulator behaves like a RAVAS RedBox on your network, so you can build and test your integration before the hardware arrives. It speaks this protocol version with the same framing, ports, responses and error codes as a RedBox with ESP32 firmware 1.5.10. Once your application works against the simulator, point it at the address of the real RedBox and it works there too.
A simulator, not a scale
The simulator is for testing integrations only. Every weight it reports is simulated. Never
use it, or anything built on its readings, for real weighing, trade, invoicing or any legal
purpose. A client can recognise it by its serial number (system parameter SERIAL_NUMBER),
which starts with SIMULATOR-.
Getting the simulator
Download the simulator from its download page, which lists every version and explains how to use it. Every version is also listed under Releases.
It is a single file for Windows (10 or 11, 64-bit) or Linux (x86-64, glibc 2.35 or later, such as Ubuntu 22.04 or Debian 12). There is nothing to install, and it needs no RAVAS hardware. Start it, and it opens its web interface at http://localhost:8080 and prints the addresses your application can connect to.
Connecting your application
Connect exactly as you would to a RedBox (see Transport layer):
| What | Value |
|---|---|
| TCP | port 49112 on the computer running the simulator, at most 4 connections at a time |
| Discovery | an empty UDP datagram to port 49111 is answered with an empty datagram |
| Framing | 0x3A, u16 little-endian length, protobuf Request / Response (packet structure) |
| Serial | optional, RS232 or RS485, see Serial: RS232 or RS485 |
| Third-party login | partner / redbox-sim |
Login
The simulator accepts its own test account for USER_LOGIN. On a real RedBox, use the
third-party account you receive from RAVAS.
Discovery on the same computer
Windows does not always deliver a broadcast to a program on the same computer. When the
simulator runs on the computer you develop on, also send the discovery datagram to
127.0.0.1, or connect by address. If another program already uses UDP port 49111, the
simulator says so when it starts.
Simulating the scale
The Simulator tab of the web interface is the scale itself:
| Section | What it does |
|---|---|
| Indicator | Shows the reading the way a correct client shows it, including the validity flags |
| Indicator keys | Zero, tare, zero-or-tare, clear tare, manual and preset tare, totalising and storing to the alibi memory, as an operator presses them. They follow the same rules as the protocol requests |
| Load | A knob for the load on the scale, with quick buttons for Max, overload and underload, and settings for the settle time, noise and a load that keeps moving |
| Tilt and load centre | A spirit level for the tilt angles and a top view of the forks for the load centre |
| Scale errors | Warm-up, ADC and loadcell faults, tilt sensor failure, side load, tip load, alibi memory full and clock not set, each with the RavasCode the RedBox reports |
| Communication faults | A response delay, frames split over several writes, a corrupted frame, ignored requests, refused connections, no discovery answer, and refusing the next request with a RavasCode of your choice |
| Device events | Power and printer events, the battery voltage, the digital inputs, a weigh-in-motion measurement and a restart |
| Alibi memory | Every stored record, with simulated history to test GET_ALIBI_LIST against |
| Traffic | Every frame your application sends and receives. Click a frame to see it byte by byte |
Scale setup and calibration are done by RAVAS and are not part of the simulator. Whoever starts
it can choose the scale model at start-up, for example --ranges 1500:0.5,3000:1 for a
dual-range scale of 3000 kg.
Building requests
The Command builder tab composes any Request from the schema. While you fill it in, it
shows how the request is built: every byte, the field key arithmetic, the length and, on serial,
the CRC. It also shows the same request as C#, Python and C (nanopb) code.
It sends the request to one of these targets and decodes everything that comes back:
| Target | Connects to |
|---|---|
| Simulator | this simulator, over TCP |
| TCP | a real RedBox on the network, found by UDP discovery or by address |
| Serial | a real RedBox on RS232 or RS485, through a serial port or USB adapter of your computer (see Serial: RS232 or RS485) |
| BLE | a real RedBox over Bluetooth |
The Decoder tab takes bytes your application sent or received, with or without the packet header, and explains them field by field.
Serial: RS232 or RS485
Besides TCP, a RedBox speaks the protocol on its RS232 or its RS485 connection. Both carry exactly the same packets; only the setting on the RedBox and the wiring differ:
| RS232 | RS485 | |
|---|---|---|
| Switch it on | system parameter RS232_PROTOCOL (12) = RS232_REDBOX (2) |
system parameter RS485_PROTOCOL (14) = RS485_REDBOX (3) |
| Baud rate | RS232_BAUD_RATE (13), default 115200 |
RS485_BAUD_RATE (15), default 1000000 |
| Wiring | point to point, full duplex (TX, RX and ground) | two-wire, half duplex |
| Devices on the line | one RedBox | one RedBox: the protocol has no bus addresses |
| Weight without subscribing | – | RS485_REDBOX_AUTO_WEIGHT_SUBSCRIBE (25) = true sends the weight unprompted from start-up |
Data bits 8, no parity, 1 stop bit. On both, every packet carries a CRC-16 after the protobuf bytes:
- CRC-16/AUG-CCITT: polynomial
0x1021, initial value0x1D0F, no reflection, no final XOR - computed over the protobuf bytes only
- appended little-endian, and not counted in the length of the header
packet-beta
title Serial packet (RS232 and RS485)
0-7: "Preamble (0x3A)"
8-23: "Length"
24-55: "Protobuf message (Length bytes)"
56-71: "CRC-16"
A RedBox ignores a packet with a wrong CRC, and drops a packet whose rest does not arrive within 1 s of its preamble.
Serial with the simulator
The simulator serves the protocol on one serial port of the computer it runs on:
--serial <port> --baud <rate>, for example --serial COM5 --baud 115200. It does not know
whether that port is RS232 or RS485: the port or USB adapter decides. To imitate a RedBox on
RS485, use a USB–RS485 adapter and the RedBox's default rate, --baud 1000000. The simulator
answers requests on RS485 as on RS232; it does not act on
RS485_REDBOX_AUTO_WEIGHT_SUBSCRIBE, so subscribe with SUBSCRIBE_WEIGHT.
The command builder's Serial target works the same way towards a real RedBox: choose the port of the RS232 or RS485 adapter and the RedBox's baud rate.
To test serial without hardware, connect the simulator and your application through a virtual
null-modem pair: com0com on Windows, or
socat -d -d pty,raw,echo=0 pty,raw,echo=0 on Linux.
Checking your client
The simulator does what a RedBox does, including what clients often get wrong:
- A
resultofOKarrives as an empty message, because proto3 does not send default values. - A payload is sent even at its default value:
Uint32 = 0selects scale 0. A request for a scale without a payload is refused withINVALID_PAYLOAD_TYPE. - Subscriptions send messages with
message_id0 in between the answers to your requests. SET_TAREtoggles: a secondSET_TAREclears the tare.SET_PARAMETERanswers twice: first aparameter, then aresult.- Responses can carry fields that
redbox.protodoes not list. Your decoder must skip them. - A request that does not decode, or is longer than 256 bytes, closes the TCP connection.
- Whether a weight may be stored follows from the gross weight: a negative net weight under a tare can still be stored.
Limits
- The simulator has one scale with up to 32 loadcells. Requests for other scales are answered as a RedBox without those scales answers them.
- It offers the partner subset of the parameters: the pages and parameters listed in this manual.
- It can not act as a RedBox over BLE. BLE in the command builder only connects to real hardware.