You can access Ubidiums' data via an API based on Protocol Buffers / gRPC. They listen on all local interfaces on port 443 and provide a TimingSystem server.
Ubidiums will also be able to connect to remote servers running a very similar API. You will have to implement a TimingServer server therefor.
You can create source code for many languages by translating the provided .proto files using the protoc compiler.
Using our Ubidium SDK can help you to get started with developing your own gRPC client or custom server.
Our SDK provides basic examples of TimingSystem clients and TimingServer servers in several programming languages.
Meanhwile examples in Go, C#, Java, Python and C++ can be found along with a wrapper for C.
All of these can only help you to get started and are all but complete.
You can find both, the .proto files and the examples, attached to this article.
The documentation of the API is provided as comments in the .proto files and here in the knowledge base.
Services
TimingSystem
TimingSystem is the service that is running as a server on Ubidiums. You can create
a TimingSystem client to communicate with local Ubidiums.
| Method Name | Request Type | Response Type | Description |
| OpenPassingStream | PassingRequest stream | PassingResponse stream |
OpenPassingStream opens a bi-directional passing stream to receive passings. |
| OpenPrewarnStream | PrewarnRequest | PrewarnResponse stream |
OpenPrewarnStream opens a bi-directional prewarn stream to receive prewarns. |
| OpenStatusStream | StatusRequest stream | StatusResponse stream |
OpenStatusStream opens a bi-directional status stream to receive status updates. |
| OpenCommandStream | CommandRequest stream | CommandResponse stream |
OpenCommandStream opens a bi-directional command stream to send commands. Note that a TimingSystem client does not need to work with command streams, but can call the commands directly. |
| NewFile | CmdNewFile | CmdNewFileResponse |
NewFile creates a new file. |
| SetTime | CmdSetTime | CmdSetTimeResponse |
SetTime sets the time. |
| GetScreen | CmdGetScreen | CmdGetScreenResponse |
GetScreen gets an image of the current screen contents. |
| PressKey | CmdPressKey | CmdPressKeyResponse |
PressKey simulates a key press. |
| SetSettings | CmdSetSettings | CmdSetSettingsResponse |
SetSetting sets the values of a set of settings. |
| GetSettings | CmdGetSettings | CmdGetSettingsResponse |
GetSetting receives the values of a set of settings. |
| Reboot | CmdReboot | CmdRebootResponse | Reboot triggers a reboot of the system. |
| Ping | CmdPing | CmdPong | Ping can be used to keep the connection alive. |
TimingServer
TimingServer is the service that you can use to communicate with non-local Ubidiums.
You can create a TimingServer server and configure Ubidiums to connect to it.
In this case the Ubidium acts as RPC client so the requests and responses are swapped, when compared to the
TimingSystem service.
| Method Name | Request Type | Response Type | Description |
| OpenPassingStream | PassingResponse stream | PassingRequest stream |
OpenPassingStream opens a bi-directional passing stream to receive passings. Ubidiums will call this method and always try to hold one stream open. |
| OpenStatusStream | StatusResponse stream | StatusRequest stream |
OpenStatusStream opens a bi-directional status stream to receive status updates. Ubidiums will call this method and always try to hold one stream open. |
| OpenCommandStream | CommandResponse stream | CommandRequest stream |
OpenCommandStream opens a bi-directional command stream to receive commands. Ubidiums will call this method and always try to hold one stream open. Since the timing server acts as RPC server, the stream is required to allow the TimingServer to execute commands on the clients (Ubidiums). |
Methods
Global messages
Passing
Passing
Passing represents a single transponder passing.
| Field | Type | Label | Description |
| id | uint64 |
per Ubidium unique ID |
|
| no | Passing.No |
passing number |
|
| src | Passing.Src |
source of the passing |
|
| transponder | Transponder |
transponder that passed |
|
| time | Time |
passing time |
|
| received | Time |
approximate time the passing was received by the Ubidium |
|
| hits | uint32 |
Number of hits |
|
| rssi | int32 |
RSSI |
|
| location | Location | optional |
Location of passing |
| active | Passing.ActiveData |
active data if this passing is an active passing |
|
| passive | Passing.PassiveData |
passive data if this passing is a passive passing |
|
| marker | Passing.MarkerData |
marker data if this passing is a marker |
Passing.ActiveData
ActiveData holds additional data of an active passing.
| Field | Type | Label | Description |
| loop_only | bool |
loop only flag |
|
| loop_id | uint32 |
loop ID |
|
| channel | uint32 |
loop channel |
|
| flags | uint32 | flags |
Passing.MarkerData
MarkerData holds additional data of a marker.
| Field | Type | Label | Description |
| loop_id | uint32 |
loop ID |
|
| channel | uint32 |
loop channel |
Passing.No
No combines a file and a passing number.
| Field | Type | Label | Description |
| file | uint32 |
file number |
|
| no | uint32 |
passing number |
Passing.PassiveData
PassiveData holds additional data of a passive passing (currently empty).
Passing.Src
Src defines a source of a passing.
| Field | Type | Label | Description |
| device_id | string |
device ID |
|
| device_name | string |
device name at the time of recording |
|
| input | string |
name of the input (sub) device that generated the passing |
|
| no | uint32 |
per source number of the passing |
Transponder
Transponder
Transponder represents an active or passive transponder or a marker
| Field | Type | Label | Description |
| id | string |
ID of the transponder |
|
| active | Transponder.ActiveData |
Active data if this is an active transponder |
|
| passive | Transponder.PassiveData |
Passive data if this is a passive transponder |
|
| marker | Transponder.MarkerData |
Marker dat aif this is a marker |
Transponder.ActiveData
Additional data if it is an active transponder
| Field | Type | Label | Description |
| wakeup_counter | uint32 |
wakeup counter |
|
| battery | uint32 |
battery level as reported from the transponder |
|
| temperature | uint32 |
transponder's temperature |
Transponder.PassiveData
Additional data if it is a passive transponder
| Field | Type | Label | Description |
| order_id | uint32 |
Order ID of normal single use transponders |
Transponder.MarkerData
Additional data if this is a marker (currently empty)
Location
Location combines latitude + longitude and an altitude.
| Field | Type | Label | Description |
| lat | double |
latitude |
|
| long | double |
longitude |
|
| alt | double |
altitude |
Time
Time combines a UTC timestamp and an offset to calculate (Ubidium's) local time.
| Field | Type | Label | Description |
| utc | google.protobuf.Timestamp |
UTC time |
|
| offset | int32 |
offset to local time in seconds |
Error
Error is an error with code and description.
| Field | Type | Label | Description |
| message | string |
text message |
|
| code | uint32 |
error number; currently used: 5 - not found |
Status
Status
Status represents a status (update) message.
| Field | Type | Label | Description |
| time | Time |
Ubidium's time when the status message was generated |
|
| id | string | optional |
device ID |
| name | string | optional |
name |
| version | string | optional |
Firmware version |
| cust_no | uint32 | optional |
configured customer number |
| passing_id | uint64 | optional |
ID of most current passing |
| passing_no | Status.PassingNo | optional |
number of most current passing |
| active_internal | Status.Active | optional |
internal active status |
| passive | Status.Passive | optional |
Status of the connected passive equipment |
| gps | Status.GPS | optional |
GPS status |
| battery_slot1 | Status.BatterySlot | optional |
status of battery slot 1 |
| battery_slot2 | Status.BatterySlot | optional |
status of battery slot 2 |
| temperature | double | optional |
current temperature (measured on the main board) |
| power | Status.Power | optional |
power status |
| update | Update | optional | firmware update status |
Status.PassingNo
Passing and/or file number
| Field | Type | Label | Description |
| file | uint32 | optional |
|
| no | uint32 | optional |
Status.Active
Status of an active device
| Field | Type | Label | Description |
| self | Status.Active.Beacon |
our beacon data |
|
| others | Status.Active.OthersEntry | repeated |
other known beacon data, key is ID |
| status | ActiveStatus | optional | status of the activeboard |
Status.Active.Beacon
Beacon
| Field | Type | Label | Description |
| channel | uint32 | optional |
loop channel |
| loop_id | uint32 | optional |
loop ID |
| power | uint32 | optional |
loop power |
| loop_status | uint32 | optional |
loop status |
| last_seen | Time | optional |
beacon time |
| mode | uint32 | optional |
mode |
| power_con | uint32 | optional |
power con |
| power_status | uint32 | optional |
power status |
| beacon_index | uint32 | optional |
beacon index |
| ch_noise_avg | uint32 | optional |
channel noise average |
| trans_lqi | uint32 | optional |
transponder LQI |
| trans_energy_detect | uint32 | optional |
transponder energy detect |
| beacon_lqi | uint32 | optional |
beacon LQI |
| beacon_energy_detect | uint32 | optional |
beacon energy detect |
| beacon_success_rate | uint32 | optional | beacon sucess rate |
| fw_version | uint32 | optional | firmware version |
| box_type | uint32 | optional | box type |
| mode_box | uint32 | optional |
beacon box mode |
| temperature | int32 | optional |
temperature |
| buffer_overflow | bool | optional | buffer overflow |
| buffer_fill_state | uint32 | optional | buffer fill state |
| avg_transponder_retries | uint32 | optional | transponder retry average |
| avg_repeat_retries | uint32 | optional | repeat retry average |
Status.Active.OptionalBeacon
OptionalBeacon is an optional beacon
| Field | Type | Label | Description |
| beacon | Status.Active.Beacon | optional |
beacon |
Status.Active.OthersEntry
| Field |
Type |
Label | Description |
| key | uint32 |
|
|
| value | Status.Active.OptionalBeacon |
|
Status.Passive
Status of passive equipment
| Field | Type | Label | Description |
| elements | Status.Passive.ElementsEntry | repeated |
known element data, key is ID |
| transponder_type | TransponderType | optional | transponder type setting |
| power | PassivePower | optional | power setting |
| has_low_power_frequency | bool | optional | true, if at least one frequency with lower power is used due to regulatory reasons |
Status.Passive.Element
Status of a single antenna element
| Field | Type | Label | Description |
| position | uint32 | optional |
element position |
| string_no | uint32 | optional |
string number the element is part of |
| status | ElementStatus | optional |
element status |
Status.Passive.ElementsEntry
| Field | Type | Label | Description |
| key | uint32 |
|
|
| value | Status.Passive.OptionalElement |
|
Status.Passive.OptionalElement
OptionalElement is an optional element
| Field | Type | Label | Description |
| element | Status.Passive.Element | optional |
element |
Status.GPS
GPS has either a fix with location or no_fix
| Field | Type | Label | Description |
| no_fix | bool |
set if there is no GPS fix |
|
| location | Location |
set to the location if there is GPS reception |
Status.BatteryData
Status of a battery
| Field | Type | Label | Description |
| level | uint32 | optional |
power level |
| remaining | google.protobuf.Duration | optional |
time until full if charging, time until empty if discharging |
| state | BatteryState | optional |
charging state of the battery |
Status.BatterySlot
A BatterySlot is either empty or has a battery (with its values)
| Field | Type | Label | Description |
| empty | bool |
|
|
| battery | Status.BatteryData |
Status.Power
Status of power supply
| Field | Type | Label | Description |
| source | PowerSource | optional |
(additional) source of power |
Update
Update delivers information about an available firmware update.
| Field | Type | Label | Description |
| installed | bool | optional |
is set if update has been downloaded and installed |
| severity | UpdateSeverity | optional |
type of firmware update |
| update_version | string | optional | version of firmware update |
BatteryState
BatteryState represents the current charging state of the battery
| Name | Number | Description |
| BATTERY_STATE_UNSPECIFIED | 0 |
|
| BATTERY_STATE_DISCHARGING | 1 |
battery is currently discharging |
| BATTERY_STATE_CHARGING | 2 |
battery is currently charging |
| BATTERY_STATE_IDLE | 3 |
battery is idle (i.e. not charging or discharging) |
PowerSource
PowerSource represents the current power source.
| Name | Number | Description |
| POWER_SOURCE_UNSPECIFIED | 0 |
|
| POWER_SOURCE_NONE | 1 |
no additional power source is used |
| POWER_SOURCE_AC | 2 |
AC is used as power source. (Battery might be used additionally.) |
| POWER_SOURCE_DC | 3 |
DC is used as power source. (Battery might be used additionally.) |
| POWER_SOURCE_USBPD | 4 |
USBPD is used as power source. (Battery might be used additionally.) |
| POWER_SOURCE_POE | 5 |
POE is used as power source. (Battery might be used additionally.) |
ElementStatus
ElementStatus represents the status of a passive antenna element
| Name | Number | Description |
| ELEMENT_STATUS_UNKNOWN | 0 |
Element status is unknown |
| ELEMENT_STATUS_OK | 1 |
Element is OK |
| ELEMENT_STATUS_BAD | 2 |
Element reports bad RSSI |
| ELEMENT_STATUS_MUTE | 3 |
Element is muted |
| ELEMENT_STATUS_UNAVAILABLE | 4 |
Element is unavailable |
ActiveStatus
ActiveStatus represents the current state of an active device.
| Name | Number | Description |
| ACTIVE_STATUS_UNKNOWN | 0 |
Active status is unknown |
| ACTIVE_STATUS_INITIALIZING | 1 | Active is initializing |
| ACTIVE_STATUS_RUNNING | 2 | Active is running |
| ACTIVE_STATUS_UPDATING | 3 | |
| ACTIVE_STATUS_FAILED | 4 | Active reports an error |
UpdateSeverity
UpdateSeverity represents the severity of an firmware update.
| Name | Number | Description |
| UPDATE_SEVERITY_UNKNOWN | 0 |
|
| UPDATE_SEVERITY_NORMAL | 1 | normal update that was found automatically or by manual update check |
| UPDATE_SEVERITY_CRITICAL | 2 | critical update that was found automatically or by manual update check |
TransponderType
TransponderType represents the current type of a passive transponder.
| Name | Number | Description |
| TRANSPONDER_TYPE_UNKNOWN | 0 |
|
| TRANSPONDER_TYPE_BIB | 1 | |
| TRANSPONDER_TYPE_TRIATHLON | 2 | |
| TRANSPONDER_TYPE_HUTAG | 3 | |
| TRANSPONDER_TYPE_SHOE | 4 |
PassivePower
PassivePower represents the current power setting for passive timing.
| Name | Number | Description |
| PASSIVE_POWER_UNKNOWN | 0 |
|
| PASSIVE_POWER_MINIMUM | 1 | |
| PASSIVE_POWER_LOW | 2 | |
| PASSIVE_POWER_MEDIUM | 3 | |
| PASSIVE_POWER_AUTO | 4 | |
| PASSIVE_POWER_MAXIMUM | 5 |
Shout
Broadcast message of Ubidium about its availability in the local network.
| Field | Type | Label | Description |
| status | Status |
current status |
|
| address | string | Ubidium's address of the network that is used to send this broadcast message |
Prewarn
Prewarn
A Prewarn holds information about an upcoming passing. They are available before the final time is determinedas,
as soon as an transponder ID is known.
| Field | Type | Label | Description |
| src | Prewarn.Src |
source of the prewarn |
|
| transponder_id | string |
ID of the transponder |
Prewarn.Src
Src is the source that is currently recording the passing.
| Field | Type | Label | Description |
| input | string |
name of the input (sub) device that generated the passing |