Conduit API Reference

HTTP

HTTP Overview

Using the HTTP API in AlphaX is a relatively simple process. The user must format his/her data in the correct format and simply use the method of choice to send and receive data from the provided URL.

NOTE: The user must first enable Conduit using his/her user profile. Follow this article here for help: https://support.minnovation.com.au/api-authentication

The user must also enable the HTTP API checkbox on the Conduit feature.

Method Action

The following HTTP methods are used to determine which action to take on a particular resource: GET Get data from resource POST Post data to a resource PUT Update a specific resource DELETE Delete a specific resource

HTTP Headers

The following HTTP headers are used by the AlphaX conduit service:

• Header Value
• Description
• Token

All requests must include a token. See specific request to determine if it should be included in the header or body of your request.

Content-Type: application/json All requests containing JSON data in the body must specify this header

Content-Encoding: gzip Request body is gzip compressed

Accept-Encoding: gzip Response will use gzip compression when content-length > 1024 bytes

X-HTTP-Method-Override:PUT, DELETE Clients not supporting PUT/DELETE methods can send via POST with this header

HTTP Parameters

API Resource requests commonly result in a response containing the current representation of one or more resources. The representations are a combination of attributes used to describe the individual resources. Consumers of Resources should tolerate the addition of new attributes and variance in ordering of attributes with ease. Not all attributes appear in all contexts. It is generally safe to consider a nulled attribute, an empty set, and the absence of an attribute as the same thing.

Request Arguments

Conduit requests allow for arguments to be specified as part of the request URL. While some resources have required arguments, most are optional and are used to alter, refine or filter the response. Arguments are specified using the standard Query string format and should be appended to the resource endpoint, prefixed with a ‘?’. https://app.alphax.cloud/conduitv6?token=xxxxxxxxxxxxxxxxxxxx&fcdt=1539792000&tcdt=1539840604 All special characters should be Url Encoded.

Attributes

Attributes are assigned specific Data types which are enforced for all requests and include:

token [REQUIRED]: The unique security token for each user. This is available from the User window in AlphaX. This parameter is required to access the conduit service, if confused about how to get token, contact Minnovation Team.

id [OPTIONAL]: The network ID that is used to register and track the device in the AlphaX system. This parameter is optional, if not defined, you will get data values for all devices the user has site access to.

ch [OPTIONAL]: The individual channel ID that is assigned within the AlphaX system. This parameter is optional, if not defined, you will get data values for all the channels of the requested devices.

fcdt [OPTIONAL]: From Created Date Time, the starting range timestamp in seconds. This parameter is optional, if not defined, you will get data values of last one hour. This parameter definition requires ‘tcdt’ parameter definition to work as desired.

tcdt [OPTIONAL]: To Created Date Time, the ending range timestamp in seconds. This parameter is optional, if not defined, you will get data values of last one hour. This parameter definition requires ‘fcdt’ parameter definition to work as desired

Note: Retrieval of data values with single GET request is limited to 1000. Only one request per minute is allowed as per rate limits.

HTTP Compression

HTTP compression is supported on both incoming and outgoing requests.

Compression is highly recommended where large requests are being submitted. We use the standard HTTP method of specifying compression encoding, with support for the gzip compression schema.

Incoming compression

In order to send compressed data to the AlphaX conduit service it is necessary to send it with gzip encoding. Compress your data using gzip and add the Content-Encoding header to your request:

Content-Encoding: gzip Outgoing compression

To receive data from the AlphaX Conduit service in gzip compressed format simply add the Accept- Encoding header to your request:

Accept-Encoding: gzip

Any response exceeding 1024 bytes will be compressed and the Content-Encoding header added.

HTTP Error and Status Codes

The Conduit service will return appropriate HTTP status codes for every request.

Error and Status Messages

Error and Status messages are always returned in a standard JSON format with the status code and message in the body of the response. An example error response {“code”:”405″,”error”:”Method Not Allowed”} Status messages are returned for certain requests that have been accepted but do not return a resource in the response body. {“code”: 304, “error”: “Operation accepted but not yet complete”}

Sending Data

How to identify the correct uplink data format and prepare your data for uplink into the AlphaX system.

What is the right format?

AlphaX uses a non-structured database and is therefore able to accept data from many sources. To ensure maximum compatibility with all data types, and provide backward and forward compatibility, we have implemented a versioning system for all of our API’s.

The version refers to the data format and can be identified as per example.

https://conduit.alphax.cloud/post/v1 —> v1 refers to the data format v1.

https://conduit.alphax.cloud/post/v2 —> v2 refers to the data format v2.

Uplink Data Format V1 (Depreciated)

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 an 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.

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 data historian 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

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.

Uplink Data Format V2

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 : array of objects // array of objects as defined below
}

Formatting the Data Array

The data array should be an array of Objects that are configured in the following key:value pair format:

data: [
 {
  channelId : integer; // the channel identifier for the value
  value : number; // the value of the data (16 digit maximum length)
  }
 ]

Example of complete data packet

{
 "token": "5b131223c67e7abcd81b0617",
 "networkId": "70B3D32111BD648F7",
 "timestamp": 1660962091000,
 "data": [
  {
   "channelId": 1,
   "value": 462.467835
   },
   {
   "channelId": 255,
   "value": 3.976
   }
  ]
 }

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.

Retrieve Data

Conduit V4 (Depreciated)

Conduit V4 provides a minimal set of data, best used for applications that require values for updates.

Example Usage – Default

https://app.alphax.cloud/conduitv4?token=xxxxxxxxxxxxxxxxxxxxxx

Returns all data from last hour.

Common Example Usage – DeviceID and Channel

https://app.alphax.cloud/conduitv4?id=21eea42dd37b&ch=4&token=xxxxxxxxxxxxxxxxxxxxxx

Returns last one hour data for Channel: 1 of Device: 21eea42dd37b

{
  "channel":4,
  "networkID":"21eea42dd37b",
  "value":0.278,
  "timestamp":"1537406384″
}

Example Usage – Date Range

https://app.alphax.cloud/conduitv4?token=xxxxxxxxxxxxxxxxxxxxxx&fcdt=1539792000&tcdt=1539840604

Returns all data values from date 1539792000 to 1539840604 for all devices the token has access to.

Conduit V6

Conduit V6 provides a full set of device data for each data point requested. Best used to register devices and update devices in other systems.

Default Usage:

https://app.alphax.cloud/conduitv6?id=21xxx42xx37x&ch=1&token=xxxxxxxxxxxxxxxxxxxxxx

Returns last one hour data for Channel: 1 of Device: 21xxx42xx37x

Get Data by Date Range

https://app.alphax.cloud/conduitv6?token=xxxxxxxxxxxxxxxxxxxxxx&fcdt=1539792000&tcdt=1539840604

{
“val_date”:1608171093,
“dev_netid”:”842D8Y118754″,
“dev_chid”:1,
“val_raw”:14,
“val_type”:”Count”,
“dev_tag”:”PAX03″,
“val_description”:”Count”,
“dev_site”:”City”,
“val_cal”:0,
“val_offset”:0,
“dev_type”:”device”,
“dev_label”:”Active”,
“dev_powersource”:”Battery”,
“dev_network”:”LTE CatM1″,
“loc_lat”:-38.146664,
“loc_lng”:145.116588,
“dev_category”:”Device”,
“dev_supplier”:”Minnovation”,
“dev_model”:null,
“dev_manufacturer”:”Minnovation”,
“val_calibrated”:14
}

Returns all data values from date 1539792000 to 1539840604 for all devices the user has site access to.

Get Last Hour Data for All Devices

https://app.alphax.cloud/conduitv6?token=xxxxxxxxxxxxxxxxxxxxxx

Returns last one hour data values for each device the user has site access to.

SSL Requests

All conduit API requests must be made over HTTPS

All API requests must be made over HTTPS. Calls made over plain http will either be redirected to https:// or fail.

You must provide a valid token for all requests.

MQTT

MQTT Overview

MQTT is a lightweight IoT protocol useful for connections with remote locations where a small code footprint is required.

MQTT is an Internet of Things connectivity protocol. It was designed as an extremely lightweight publish/subscribe messaging transport. It is useful for connections with remote locations where a small code footprint is required and/or network bandwidth is at a premium” (Source: MQTT.org).

In this section you will find the documentation needed to publish data to AlphaX over MQTT.

NOTE: The user must first enable Conduit using his/her user profile. View this article for help activating conduit.

MQTT Authentication

The user can Subscribe/Publish to the the MQTT service at mqtt.alphax.cloud using their credentials.

Enable Conduit

The user must have the MQTT checkbox enabled on the Conduit feature.

Publish/Subscribe

The user can now Subscribe/Publish to the the MQTT service at mqtt.alphax.cloud using the credentials provided.

Note: Authentication is achieved by a combination of the authenticating users password and token. It is highly recommended that this user is a special user in the system that does not normally log in.

token [REQUIRED]: The unique security token for each user. This is available from the User window in AlphaX. This parameter is required to access the conduit service, if confused about how to get token, please contact the Minnovation Team. The token will be your username.

username [REQUIRED]: The password of the user for whom the service has been enabled for. This parameter is mandatory, if not defined, you will receive an error message and not be able to connect to the MQTT service.

MQTT Broker Address

Connect to the MQTT broker using the following addresses.

You can access the API through MQTT or secure MQTT with TLS on our enterprise subscription. The following endpoints are based on your AlphaX Subscription.
AlphaX does not support fixed IPs addresses for MQTT.

Security Note: We strongly advise to use MQTT with TLS where your subscription allows to make sure your data travels encrypted, avoiding the exposure of your API token and/or sensor data to third parties

Posting Data with MQTT

Posting Data to AlphaX is a relatively simple process. The user must format his/her data in the correct format and simply publish it to the AlphaX Cloud MQTT service. The AlphaX system will automatically take care of the rest!

NOTE: The user must first enable Conduit using his/her user profile. Follow this article here for help: http://52.147.34.237/knowledge-base/how-to-enable-conduit-for-a-user/

The user must also enable the MQTT checkbox on the Conduit feature.

The user can now Subscribe/Publish to the the MQTT service at mqtt.alphax.cloud using the credentials provided.

Publish Topic:

token/id/publish/v4

token [REQUIRED]: The unique security token for each user. This is available from the User window in AlphaX. This parameter is required to access the conduit service, if confused about how to get token, please contact the Minnovation Team.

id [REQUIRED]: The unique network ID that is used to register and track the device in the AlphaX system. This parameter is mandatory, if not defined, you will receive an error message.

The payload must be the message in the standard AlphaX format.

payload[REQUIRED]: The byte array that contains the data for the publish. The data must assume the standard data format for AlphaX as documented here: http://52.147.34.237/knowledge-base/payload/

Example Usage:

Publish to mqtt.alphax.cloud

Topic: xxxxxxxxxxxxxxxxxx/mydevice1234/publish/v4

Payload: 0A10010001000000A00F0000

This would submit the data

Fixed Data Channels: 4106 1 1 0

Being default data of Battery Voltage, Message ID, RSSI and Error Code. If your device doesn’t output these values simply add a 0 to pad the data value out.

Dynamic Data Channels: 4000

Being dynamic data channel of 4000. Note this value is divided by 1000 to convert to a float on storage.

Dynamic channels can be registered in AlphaX using the following link: http://52.147.34.237/knowledge-base/how-to-configure-channel-for-an-alphax-iot-device/

MQTT Update Topics

Use this Topic to Publish data to one or more variables of a Device

To send data to AlphaX via MQTT, set the unique Device ID label in the topic path.

There are two verison of the topic structure. One is for bulk updates of a unique ID, the second is intended for individual updates of each device channel.

Bulk Update Device

{TOKEN}/{DEVICE_ID}/0/data

Single Update Channel

{TOKEN}/{DEVICE_ID}/{CHANNEL_ID}/data

Where {DEVICE_ID} is a unique identifier of the Device that data will be sent to.

 

 

TCP/UDP

Overview

The User Datagram Protocol, UDP, is also a very popular protocol but unlike TCP, it is “connectionless”.

The Transmision Control Protocol, TCP, is one of the most popular data transport protocols. That’s the reason why it is supported by default by many hardware devices.

Its main advantage comes from the packet size, which is usually lower than packets sent using HTTP/s (which in fact, uses TCP as transport layer). TCP is “connection oriented”, which means it implements confirmation methods to guarantee that data is received by the destinatary.

The User Datagram Protocol, UDP, is also a very popular protocol but unlike TCP, it is “connectionless”. This means it does not implements any confirmation method to guarantee that data is received by the destinatary. This can be an advantage in applications where simplicity and speed are more important than reliability, for example video streaming.

TCP and UDP are similar in the sense that they share the structure of an endpoint with a port.

UDP URL

Connect to the UDP broker using the following addresses.

You can access the Conduit API through UDP or secure UDP with on our enterprise subscription. The following endpoints are based on your AlphaX Subscription.

AlphaX does not support fixed IPs addresses for UDP.

UDP

Security Note: We strongly advise to use TCP with TLS where your subscription allows to make sure your data travels encrypted, avoiding the exposure of your API token and/or sensor data to third parties.