Skip to content

Start

This document aims to give a detailed overview of how to communicate with the RAVAS RedBox scale using the RedBox protocol. The protocol uses protocol buffers to encode its messages.

Glossary
  • Scale: The weighing scale. A Ravas Redbox can contain multiple weighing scales. Usually only one scale is used (Index 0)
  • Loadcell: A straingauge to measure the applied weight and converts this into a electrical signal
  • Tare: Subtracting e.g. the weight of a pallet
  • Gross weight: Total weight on the scale
  • Net weight: Weight with tare subtracted.
  • Alibi memory: The instrument's store of measurement data (WELMEC Guide 7.2, Extension L). Every stored weighing gets a unique alibi number.

Getting started

Protocol buffer decoding/encoding libraries exist for all popular languages. See: protobuf-compiler-installation.

Schema file (.proto)

The schema is published as a single file:

redbox.proto is the partner-facing subset of the RedBox protocol. Message, field and enum numbers are identical to the RAVAS internal definition, so the subset stays wire-compatible: a field you do not find in the file is simply skipped by your decoder. The file itself is the reference — this manual explains how to use it.

Note

The schema is licensed for communication with RAVAS equipment only. The full licence text is at the top of the file.

Everything in this manual is generated from that file, so the names used here (Request.Type, WeighingResult_ext, RavasCode, …) are exactly the names your protobuf compiler will produce.

Packet structure

Each packet starts with a 3 byte header. This header contains a fixed preamble byte (0x3A) and the length of the protobuf message (u16). 

packet-beta
title Packet header
0-7: "Preamble (0x3A)"
8-23: "Length"
The header is followed by Length bytes, which is the encoded protobuf message. Multiple packets can be sent one after the other. This packets will be handled sequentially.

Transport layer: TCP/IP

The protocol is available over multiple physical transport layers. For now the scope of this document is limited to the TCP/IP layer. The RedBox is listening on TCP port 49112 for a connection. Once connected, you can start sending Requests.

To discover a RedBox on the network, send an empty UDP broadcast packet to port 49111. The RedBox responds with its own empty UDP packet.

Usage

Initially the communication can follow a basic Request - Response flow.

sequenceDiagram
    Client->>RedBox: Request
    RedBox-->>Client: Response

Both Request and Response carry a message_id. Set it to any number you like on a request and the same number comes back on the matching response. It is there purely to make your client implementation easier — it becomes essential once you subscribe to events, because from that point on responses also arrive unprompted.

Where to look next

Page Contents
Request Every command you can send, and the payload each one takes
Response Every answer the RedBox sends — including the weighing result
Subscriptions Receiving weight, power and printer events unprompted
Error-handling The RavasCode list
Parameter management Reading and writing the configuration

Example

See Basic example (C#) for a minimal example.