Skip to content

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 value 0x1D0F, 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 result of OK arrives as an empty message, because proto3 does not send default values.
  • A payload is sent even at its default value: Uint32 = 0 selects scale 0. A request for a scale without a payload is refused with INVALID_PAYLOAD_TYPE.
  • Subscriptions send messages with message_id 0 in between the answers to your requests.
  • SET_TARE toggles: a second SET_TARE clears the tare.
  • SET_PARAMETER answers twice: first a parameter, then a result.
  • Responses can carry fields that redbox.proto does 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.