Uplink Data Format V1

Data format V1 allows users to compress their payload and retain the convenience of JSON readable header information for reduced size and performance.

Best for Edge to Cloud transfers

AlphaX expects a JSON formatted object with the following key:value pair format, and populated with the following data types.

{
  token : string; // conduit token from AlphaX Cloud
  networkId : string; // unique identifier on the network
  timestamp : integer; // 13 digit UTC timestamp
  data : bytearray; // byte array formatted as string and
  // configured as per examples below
}

Formatting the Data Object

In a V1 n-byte payload, the first 8 bytes are mandatory and always corresponds to device level data. Any bytes after these mandatory bytes corresponds to individual channel data.

The data object should be formatted as a byte array using the following structure.

data: 0A10010001000000A00FA00F0000

Mandatory Data (Device Data)

Device data is mandatory when using the v1 packet format. This data refers to the first 8 bytes of data in the bytearray string which are mapped to 4 reserved channels in the AlphaX system when it receives an uplink message.

Byte Number	Data Type	Mapped to Channel	Expected units
1-2	Device Voltage	255	milliVolts (int)
3-4	Signal Strength	254	RSSI (int)
5-6	Message ID	253	Count (int)
7-8	Error Code	252	Error ID (int)

Tip: If the data is not available for the data specified, or should the user wish to pass these values in alternative channels, you can pad any of the listed fields using 0000

Dynamic Data (Channel Data)

Following the mandatory fields, each channel specific values can be passed as a 4 byte integer. These integers will dynamically fill channels starting at channel 1 up to channel 32 for each 4 byte integer that is added to the end of the packet.

These values are divided by 1000 before being stored in the database to accomodate for floating point precisions.

Tip: If more than 3 decimal places are required, we suggest choosing a different data uplink format for ingestion eg. v2 or v3

Byte Number	Data Type	Mapped to Channel	Expected Units
9-12	Channel Value	1	value * 1000 (int)
13-16	Channel Value	2	value * 1000 (int)
17-20	Channel Value	3	value * 1000 (int)
…	…	…	…
133-136	Channel Value	32	value * 1000 (int)

Note: AlphaX has a limit of 32 data channels per device. Should additional channels be required, we suggest splitting the data over 2 seperate data sources.

Example of correct data packet

{
  "token": "5b131223c23a7abcd81b0617",
  "networkId": "70B3D32111BD648F7",
  "timestamp": 1660962091000,
  "data": 0A10010001000000A00FA00F0000
}

Note: AlphaX has several reserved channels. These are outlined in the channel plan help article. Please ensure that channel ID’s are correctly mapped to these channel numbers to take advantage of features such as battery life predictions and auto Geo-Location of devices.