Generic TCP importer

Using a very simple text-based TCP protocol, you can have your own devices or integration component connect into BBT, and import raw time records this way, just like any natively supported box.

You can connect as many devices as you like, with each connection representing a device with an identifier of your choice. The default port is 12368, but this can be changed via the advanced event setting ext.generictcp.inbound.port.

The protocol is designed for simplicity and is based on a simple request-response pattern where each communication is initiated by the external caller, and all commands result in exactly one reply. Commands are send in UTF-8 text, and seperated by a newline (\r\n).

Commands and arguments are separated by semicolons. Named arguments are formatted as “key=val”. Each response is an echo of the command followed by either “ok” or “error” as the first argument. In case of “error”, an optional second argument may include an error message.

The first command sent must be “hello”, and include the protocol version (current is 1), and the identifier of the device. The identifer can consist of letters, numbers, underscore and dash, and is something you decide upon to distinguish it from other TCP importers you might use (like MyDevice). The identifier will be used inside BBT to assign the device to an event.

Example command:
hello;v=1;identifier=MyDevice

Response:
hello;ok;host= Black Box Timing

A timing record can be sent to the software using the record.add command.
Arguments are tag (chip code, rfid tag id, race number or similar), time (timestamp of the record), id, antenna and signal.
Only tag and time are required, and the argument order is irrelevant.
id is a unique 64-bit integer for this record if you wish to update it later, and is optional.
time should be in the format yyyy-mm-ddTHH:mm:ss.ffffff (24 hour time, in local time zone)

Example commands:
record.add;tag=ABC12345;time=2024-08-15T23:11:12.123456
record.add;tag=ABC12345;time=2024-08-15T23:11:12.123456;id=42;signal=-4.22;antenna=3

Responses:
record.add;ok
record.add;ok;id=42

Records can be updated using the record.update command. The arguments are the exact same as for record.add, but id is required. If a record with the provided id does not exist, it might be created.

It is possible to send periodic device status information, such as vendor, model, battery information, GPS position, firmware version, read rates and much more. Contact us for details on the supported values.

Example command:
status;device.vendor=My company;device.model=Cool Device Pro;power.battery.available=1;power.battery.pct=53;gps.satellites=7;temp.cpu=42

Responses:
record.status;ok

At least one command should be sent every 10 seconds. If no data is received for a while, the connection will be terminated. You can send the “ping” command (with no parameters) to keep the connection alive.

Example command:
ping

Response:
ping;ok