# API Introduction AlphaX Cloud's API codenamed Conduit, is our modern API designed to seamlessly transport data from the edge into the enterprise for downstream consumption. Understanding the diverse needs of our users, Conduit is built with modularity at its core, offering the flexibility to select from a variety of input and output versions and formats to best suit your project requirements. Here’s how Conduit stands to benefit our users: #### Flexibility and Customization Conduit’s modular design enables users to tailor the data processing pipeline according to their specific needs. Whether your focus is on real-time analytics, machine learning model training, or any other data-driven initiative, Conduit allows you to choose the input and output configurations that best align with your objectives. #### Streamlined Data Integration By serving as a comprehensive conduit for data, our API simplifies the complexity associated with transporting data across various stages of the enterprise ecosystem. This streamlined approach reduces the overhead and potential bottlenecks often encountered when managing data flow, facilitating a smoother integration process. #### Enhanced Data Management Conduit empowers users with superior control over their data management processes. By providing options for different data versions and formats, users can ensure that their data is always in the right form for their needs, enhancing both efficiency and effectiveness in data utilization. #### Scalability Designed to support enterprises at any scale, Conduit is capable of handling the increasing volumes of data characteristic of growing businesses. This scalability ensures that as your data needs evolve, Conduit will continue to provide the robust support necessary for your success. #### Reliability and Security We understand the critical importance of data integrity and security. Conduit is built with industry-leading security measures, ensuring that your data remains secure throughout its journey from the edge to enterprise consumption. In summary, Conduit by AlphaX Cloud offers a flexible, efficient, and secure way to manage the flow of data within your enterprise. Its modular design, combined with the ability to customize data inputs and outputs, makes it an invaluable tool for businesses looking to optimize their data infrastructure without compromising on security or scalability. Experience the difference with Conduit—where data moves seamlessly, so your business can too. # General Architecture AlphaX splits its services into 2 general components, Data In and Data Out, these are sometimes referred to as upstream and downstream. #### Overview The architecture of the AlphaX Cloud's Conduit API, as detailed in the provided document, encompasses a comprehensive ecosystem designed to facilitate efficient data flow from field devices to enterprise-level applications.

General Architecture of AlphaX API

#### The key components of the architecture include: 1. **Field Devices:** These are the initial sources of data, encompassing a variety of sensors and devices deployed in the field. 2. **MQTT Service:** A messaging protocol that allows for the secure and efficient transmission of data between devices and the server. 3. **LoRaWAN Network Server:** This component manages communication between field devices and the network using the LoRaWAN protocol. 4. **AlphaX Web Application:** An interface for users to interact with the system, configure settings, and visualize data. 5. **AlphaX Storage:** The data storage solution within the architecture, designed for high availability and reliability. 6. **Gatekeeper Service:** Manages authentication and authorisation to ensure secure access to system resources. 7. **HTTP GET Services (V4, V6, and V7):** These are the core components allowing for modular data input and output configurations, ensuring flexibility and scalability in data management and integration. 8. **HTTP POST Services:** This is a HTTP Post service designed for trasferring data from other cloud based applications or sensors and devices with HTTP capability Each component plays a critical role in ensuring that data flows seamlessly from the edge into the enterprise for analysis and consumption, providing a robust framework for managing complex data ecosystems. # Authentication The Conduit feature enhances data import/export security via a token and server-side validation, activated individually for users, allowing token-authenticated access to user-specific data. The Conduit feature adds a layer of security when importing and exporting data by adding a security token and server-side validation when passing data requests. It is activated per user on a one-by-one basis. When conduit is activated, the token allows the service to access all of the data that the user has access to, with the same level of authority and roles. #### Activating Conduit To activate it for one of your users (or yourself) log into the AlphaX system and follow the instructions below. * Navigate to People->Users in the main Navigation Menu * Select the user that Conduit should be enabled for. * Toggle the “Enable Conduit” Switch. * Click the Save button. * The Conduit Token ID will be displayed for that user # Rate Limits The conduit API service is throttled by default. One request is allowed every (n) number of seconds. Requests that exceed this limit will receive a 429 Too Many Requests response. {% hint style="warning" %} Note the maximum timerange that can be requested by all API's is 31 days. This limit applies to all API calls for retrieving data. {% endhint %} {% hint style="warning" %} AlphaX applies a maximum of 843000 datapoints into the aggregation (i.e. Raw records that will be grouped and sorted). A maximum of 105120 datapoints will be outputted per sensor in the API output. {% endhint %} #### **Reading Data** Rate limiting applies to the rate at which you can request API data from the conduit service. limits are based on the AlphaX IoT subscription assigned to the users token. * Standard: Rate limited to 1 call per 10 seconds, 1000 record limit * Pro: Rate limited to 1 call per second, 1000 record limit * Enterprise: No Rate limits apply. NOTE: We recommend requesting one large amount of data up to 31 days rather than many small requests. #### **Writing Data** * Standard: Rate limited to 100 writes per second. * Pro: Rate limited to 100 writes per second. * Enterprise: No Rate limits apply. # HTTP 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. *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 AlphaX conduit service utilizes specific HTTP headers for authentication, data format specification, compression, and method override within requests and responses. **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 Ar*guments* 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 ‘?’. ```url https://api.alphax.cloud/conduitv6?token=xxxxxxxxxxxxxxxxxxxx&fcdt=1539792000&tcdt=1539840604 e ``` 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 {% hint style="danger" %} Retrieval of data values with single GET request is limited as per your AlphaX Cloud subscription. [Refer here for limits that apply](/rate-limits) {% endhint %} # 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: ```json { “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. Example: ```json { “code”: 304, “error”: “Operation accepted but not yet complete” } ``` #### Status Codes | Code | Satus | Description | | ---- | --------------------- | --------------------------------------------------------- | | 200 | Ok | Completed Successfully | | 304 | Not Modified | There was no new data to return | | 400 | Bad Request | The request was invalid or cannot be otherwise served | | 401 | Unauthorised | Authentication failed | | 403 | Forbidden | No permission for the HHTP method or requested resource | | 404 | Resource not Found | Requested resource not found | | 405 | Method Not Allowed | Resource does not support the requested HHTP Method | | 413 | Request too large | Requested time range is greater than maximum 31 day limit | | 429 | Too Many Requests | Request has been rejected for exceeding usage limits | | 500 | Internal Server Error | Error occurred processing the request | | | | | # 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. # 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. {% hint style="success" %} —> v2 refers to the data format v2. {% endhint %} # Uplink Data Format V2 AlphaX API expects JSON with token, networkId, timestamp, and data array containing channelId and value. Supports advanced data integration and security features. {% hint style="success" %} **Best for Cloud to Cloud transfers** {% endhint %} AlphaX expects a JSON formatted object with the following key:value pair format, and populated with the following data types. ```json { 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: ```json 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** ```json { "token": "5b131223c67e7abcd81b0617", "networkId": "70B3D32111BD648F7", "timestamp": 1660962091000, "data": [ { "channelId": 1, "value": 462.467835 }, { "channelId": 255, "value": 3.976 } ] } ``` {% hint style="warning" %} **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. {% endhint %} # Retrieve Data # Conduit V4 Conduit V4 provides a minimal set of data, best used for applications that require values for updates where device data is already known. {% hint style="danger" %} SECURITY NOTE: Conduit V4 uses GET method so request data forms part of the URL. This means your security token could potentially be stored in browser history or in web server logs. {% endhint %} #### Parameters [See section for HTTP parameters](/http/http-parameters). #### HTTP Method GET Request #### Base URL ```url https://api.alphax.cloud/conduitv4 ``` #### Example Usage – Default ``` https://api.alphax.cloud/conduitv4?token=xxxxxxxxxxxxxxxxxxxxxx ``` Returns all data from last hour that the user has access to. #### Common Example Usage – DeviceID and Channel ``` https://api.alphax.cloud/conduitv4?id=21xxx42dd37b&ch=4&token=xxxxxxxxxxxxxxxxxxxxxx ``` Returns last one hour data for Channel: 1 of Device: 21xxx42dd37b ```json { "channel":4, "networkID":"21xxx42dd37b", "value":0.278, "timestamp":"1537406384″ } ``` #### Example Usage – Date Range ``` https://api.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. {% hint style="danger" %} SECURITY NOTE: Conduit V6 uses GET method so request data forms part of the URL. This means your security token could potentially be stored in browser history or in web server logs. {% endhint %} #### Parameters [See section for HTTP parameters](/http/http-parameters). #### HTTP Method GET Request #### Base URL ```url https://api.alphax.cloud/conduitv6 ``` #### Default Usage: ```url https://api.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 ```url https://api.alphax.cloud/conduitv6?token=xxxxxxxxxxxxxxxxxxxxxx&fcdt=1539792000&tcdt=1539840604 ``` ```json { "val_date":1608171093, "dev_netid":"842D8Yxxx754", "dev_chid":1, "val_raw":14, "val_type":"Count", "dev_tag":"PAX03", "val_description":"Count", "dev_site":"City", "val_cal":0, "val_offset":2, "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":16 } ``` 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 ```url https://api.alphax.cloud/conduitv6?token=xxxxxxxxxxxxxxxxxxxxxx ``` Returns last one hour data values for each device the user has site access to. # Conduit V7 This guide provides detailed support for the API endpoint that supports multi-stage aggregations for time series data. #### Introduction In today’s digital age, having the ability to process and interpret large volumes of data is crucial. With our Multi-Stage Data Aggregation API, you can do just that, and with greater precision than ever before. This API stands out by providing up to 4 stages of data aggregation tailored to your specific requirements. This helps users normalise and transform data before passing to downstream applications. It is also useful in reducing data transfer size and minimising the number of records in the downstream application. # Using Conduit V7 API Parameters When timerange Applied and Valid, return the data from last timerange seconds. When timerange Not Applied or Invalid and fcdt & tcdt Applied and Valid, return the data from fcdtto tcdt. {% hint style="danger" %} SECURITY NOTE: Conduit V7 uses GET method so request data forms part of the URL. This means your security token could potentially be stored in browser history or in web server logs. {% endhint %} #### Pre-requisites Before you can access the API endpoint, ensure that: * You have a valid token for authentication. * If you haven’t activated your token yet, please refer to on how to enable Conduit for a user #### HTTP Method GET Request #### Base URL ```url https://api.alphax.cloud/conduitv7 ``` ### API Parameters
ParameterDescriptionInputRequired
tokenThe unique security token for each user. This is available from the User window in AlphaX.StringRequired
fcdt

From Created Date Time, the starting range timestamp in seconds.

If not defined, you will get data of last one hour.

This parameter definition requires valid ‘tcdt’ parameter definition to work as desired.

10 digits IntegerOptional
tcdt

To Created Date Time, the ending range timestamp in seconds.

If not defined, you will get data of last one hour.

This parameter definition requires valid ‘fcdt’ parameter definition to work as desired

10 digits IntegerOptional
timerange

Date time range in seconds.

Valid Values:

3600(Last 1 Hour), 86400(Last 24 Hours),

604800(Last 7 Days), 2592000(Last 30 Days)

IntegerOptional
id

The network ID that is used to register and track the device in the AlphaX system.

If not defined, you will get data values for all devices the user has site access to.

StringOptional
ch

The individual channel ID that is assigned within the AlphaX system.

If not defined, you will get data values for all the channels of the requested devices.

IntegerOptional
siteid

The id of Entity(Heirarchy). You will get data values for all devices that assigned to the site and its sub sites.

If not defined, you will get data values for all devices the user has site access to.

StringOptional
showhidech

If true, include channels marked as hidden in the AlphaX platform.

Default functionality is to not provide channels that are hidden.

booleanOptional
tagfilterIf defined, retrieve only the devices whose tags include the input string.StringOptional
statusIf defined, retrieve only the devices whose status(labelName) include the input string.StringOptional
limit

Maximum amount of datapoints per sensor(channel).

If is 0 or not defined, the limit is 100000.

Integer

(0-100000)

Optional
timezone

Output timezone.

If not defined, use the timezone of the token.

If the timezone of the token is not defined, use ‘GMT’.

StringOptional
groupby

Group type.

If not defined, group & aggregate are disabled. You will get live data values.

StringOptional
aggregateby

aggregate type.

If not defined, group & aggregate are disabled. You will get live data values.

StringOptional
pregroup1Pre group type#1StringOptional
preaggregate1Pre aggregate type #1StringOptional
pregroup2Pre group type#2StringOptional
preaggregate2Pre aggregate type #2StringOptional
pregroup3Pre group type#3StringOptional
preaggregate3Pre aggregate type #3StringOptional
#### Date Ranges {% hint style="warning" %} When `timerange` Applied and Valid Conduit will return the data from current date/time minus `timerange` in seconds. If `timerange`Not Applied or timerange not valid ConduitV7 will return data for last 1 hour. {% endhint %} {% hint style="warning" %} When `fcdt` & `tcdt` applied and valid, conduit will override timerange and return the data from `fcdt`to `tcdt`as long as they remain within the limit set and/or [rate limt of the API](/rate-limits). {% endhint %} ### Data Format The response from the API will be in the JSON format. Below is the structure of the data you will receive. ```json [{ "channelDescription": "", "id": "", "chid": "", "netid": "", "data": [ {"timestamp": "", "value": ""}, {"timestamp": "", "value": ""} // Repeats for all valid data ], "deviceName": "", "labelColor": "", "labelName": "", "location": "", "locationSensor": "", "tag": "", "unit": "", "timezone": "", "siteid": "", "sensorType": "", "limitData": "", "limitOutput": "", "cal": "", "offset": "", "maxVal": "", "minVal": "" }] ``` ### Field Descriptions * **channelDescription**: Description of the channel. * **id**: Unique identifier for the sensor. * **chid**: Channel identifier. * **netid**: Network identifier. * **data**: Array of data points, each containing a timestamp and value. * **deviceName**: Name of the device. * **labelColor**: Color assigned to the label. * **labelName**: Name of the label. * **location**: Information about the location of sensors. * **locationSensor**: Location sensor information for virtual channels. * **tag**: Tag related to the device. * **unit**: Measurement unit of the data. * **timezone**: The timezone in which the data is represented. * **siteid**: Entity identifier. * **sensorType**: Type of sensor. * **limitData**: Indicates if the input record limit has been reached (maximum of 843000 datapoints). * **limitOutput**: Indicates if the request data limit has been reached (maximum of 105120 datapoints). * **cal**: Data calibration factor. * **offset**: Data calibration offset. * **maxVal**: Maximum data value. * **minVal**: Minimum data value. # Aggregation Features (Optional) Aggregations are used to transform the data before loading into a downstream application. It can be useful to reduce the amount of data transfer and apply simple calculations on the fly. ### Practical Examples To better understand the functionality and practicality of this tool, let’s delve into some real-world operational scenarios: **Energy Management:** * Use cumulative aggregation grouped by days to track energy consumption over time. * Pre-stage with an average aggregation by hours to identify average energy usage for the period cumulated. **Occupancy Data:** * Use count aggregation grouped by weeks to find out the number of visitors per week. * Pre-stage with maximum aggregation by hours to determine the maximum number of occupants over the week. **Meteorology Data:** * Use range aggregation grouped by months to identify monthly temperature fluctuations. * Pre-stage with average aggregation by days to understand daily temperature trends within those months. These applications are just a glimpse of what’s achievable with the Multi-Stage Data Aggregation API. Depending on your needs, this tool can be tailored to deliver precise and actionable insights and only limited by your creativity. ### Aggregation parameters **Aggregation Methods:** You can select from one of the following aggregation outputs: * Count * Sum * Average * Maximum * Minimum * Range * Difference * Cumulative **Aggregation Groupings:** The above aggregations can be grouped by the following: * Minutes * Hours * Days * Weeks * Months * Years #### Single Stage Aggregation Parameters All aggregations must use a final groupby and aggreagteby stage. | Parameter | Valid Values | Sequence | | ----------- | ------------------------------------------------- | ---------------------- | | groupby | `minute` , `hour`, `day`, `week`, `month`, `year` | groupby -> aggregateby | | aggregateby | `sum`, `avg`, `max`, `min`, `range`, `diff` | | #### Multi Stage Aggregation Parameters
ParameterValid ValuesSequence When Apply
pregroupminute , hour, day, week, month

pregroup1 & preaggregate1 → groupby & aggregateby

preaggregate1sum, avg, max, min, range
pregroup2hour, day, week, month

pregroup1&preaggregate1 →

pregroup2 & preaggregate2 →

groupby & aggregateby

preaggregate2sum, avg, max, min, range
pregropregroup3day, week, month

pregroup1 & preaggregate1→

pregroup2 & preaggregate2→

pregroup3 & preaggregate3→

groupby & aggregateby

preaggregate3sum, avg, max, min, range
When `Multi-stage Aggregation` parameters Applied, `Aggregation` is the Last stage; When `Multi-stage Aggregation` parameters Not Applied, `Aggregation` is the Only stage; For `group` parameter, the time range of Previous Stage must be Shorter. For example, If `groupby` is ‘hour’, `pregroup1` must be ‘minute’ and `pregroup2 & 3` and `preaggregate2 & 3` cannot be applied. Other wise the data won’t be accurate. # Common Issues & Troubleshooting The ConduitV7 API is complicated. Below are some common issues and troubleshooting tips to help you solve problems you may encounter while using the ConduitV7 API. 1. **Authentication Error**: If you receive an authentication error, ensure that you are using a valid token. If you have not activated your token, refer to the above-mentioned help article. 2. **Data Limit Reached**: * If `limitData` returns `true`, you have reached the maximum record input limit. Consider filtering or reducing the amount of data you are sending. * If `limitOutput` returns `true`, you have reached the maximum request data limit. Consider requesting data in smaller batches or within a narrower timeframe. 3. **Data Inconsistencies**: If the data seems inconsistent or doesn’t match expected values, check the `cal`and `offset` values. These represent calibration factors and offsets applied to the data. 4. **Timezone Issues**: Ensure that the `timezone` field matches your expected timezone, as it can impact the interpretation of `timestamp` values in the data. 5. **No Data Received**: If you do not receive any data, ensure that your request parameters (such as date ranges, sensor ids, etc.) are correctly set. # Usage Examples These examples provide a starting point and can be modified based on your specific requirements. Always ensure that you are using the correct parameters and their values for successful data retrieval **How to Use The Examples** 1. Replace \`xxxxxxxxxxxxxxxxxxxx\` with your valid token. 2. Replace \`xxxxxxxxxx\` in \`fcdt\` and \`tcdt\` with your desired start and end time respectively in 10 digit unix timestamp format. 3. If you are accessing data for a specific entity, replace \`xxxxxxxxxxxxxxxxxx\` in \`siteid\` with your entity ID. Support Article here: [https://minnovation.com.au/knowledge-base/how-to-find-the-id-of-an-entity-in-alphax/ ](https://minnovation.com.au/knowledge-base/how-to-find-the-id-of-an-entity-in-alphax/) ### ConduitV7 Examples #### Get hourly sum from all channels of device xxx-cam-010 in a time range: ```url https://api.alphax.cloud/conduitv7?token=xxxxxxxxxxxxxxxxxxxx&fcdt=xxxxxxxxxx&tcdt=xxxxxxxxxx&id=xxx-cam-010&groupby=hour&aggregateby=sum ``` #### Get hourly sum from channel 1 of device cos-cam-010 in a time range ```url https://api.alphax.cloud/conduitv7?token=xxxxxxxxxxxxxxxxxxxx&fcdt=xxxxxxxxxx&tcdt=xxxxxxxxxx&id=xxx-cam-010&ch=1&groupby=hour&aggregateby=avg ``` #### Get raw data from all devices of an entity in the last 1 hour ``` https://api.alphax.cloud/getHourlyData?token=xxxxxxxxxxxxxxxxxxxx&siteid=xxxxxxxxxxxxxxxxxx ``` #### Get daily range of hourly average from all devices of the entity that the token is assigned to in a time range ``` https://api.alphax.cloud/conduitv7?token=xxxxxxxxxxxxxxxxxxxx&siteid=xxxxxxxxxxxxxxxxxx&fcdt=xxxxxxxxxx&tcdt=xxxxxxxxxx&aggregateby=range&groupby=day&preaggregate1=avg&pregroup1=hour ``` # MQTT 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](https://mqtt.org/)). In this section you will find the documentation needed to publish data to AlphaX over MQTT. {% hint style="info" %} NOTE: The user must first enable Conduit using his/her user profile. View this article for help [activating conduit](https://minnovation.com.au/knowledge-base/how-to-enable-conduit-for-a-user/). {% endhint %} # 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. {% hint style="info" %} 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. {% endhint %} **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 | URL | Port | Subscription | | ------------- | ----------------- | ---- | -------------- | | MQTT (No TLS) | mqtt.alphax.cloud | 1883 | Basic, Premium | | MQTTS (TLS) | mqtt.alphax.cloud | 8883 | Enterprise | {% hint style="danger" %} 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 {% endhint %} # Publishing Data # MQTT Publish Format V1 MQTT Publish format V1 is the compressed format, useful for data constrained devices. Data remains in byte array and decoded in AlphaX cloud. {% hint style="success" %} **Best for Edge to Cloud transfers** {% endhint %} 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! {% hint style="info" %} NOTE: The user must first enable Conduit using his/her user profile. Follow this article here for help: [**https://minnovation.com.au/knowledge-base/how-to-enable-conduit-for-a-user/**](https://minnovation.com.au/knowledge-base/how-to-enable-conduit-for-a-user/) {% endhint %} 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 V1: \/\/pub/v1 **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. **device 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. ### Publish Message V1 **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: #### 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) | {% hint style="info" %} 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 {% endhint %} #### 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. {% hint style="info" %} Tip: If more than 3 decimal places are required, we suggest choosing a different data uplink format for ingestion eg. v2 or v3 {% endhint %} | 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) | | … | … | … | … | | 73-76 | Channel Value | 16 | value \* 1000 (int) | {% hint style="info" %} Note: AlphaX has a limit of 16 data channels per device. Should additional channels be required, we suggest splitting the data over 2 seperate data sources. {% endhint %} ### Example Usage Publish to mqtt.alphax.cloud #### Topic ``` xxxxxxxxxxxxxxxxxx/mydevice1234/pub/v1 ``` #### Message ``` 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: [**https://minnovation.com.au/knowledge-base/how-to-configure-channel-for-an-alphax-iot-device/**](https://minnovation.com.au/knowledge-base/how-to-configure-channel-for-an-alphax-iot-device/) # MQTT Publish Format V2 MQTT Publish format V2 is a user friendly, human readable JSON package for sending data to a device on AlphaX Cloud. {% hint style="success" %} **Best for Cloud to Cloud transfers** {% endhint %} Publishing Data to AlphaX Cloud using is a relatively simple process. The user must format his/her data in the correct way and simply publish it to the AlphaX Cloud MQTT service. The AlphaX system will automatically take care of the rest! {% hint style="info" %} NOTE: The user must first enable Conduit using his/her user profile. Follow this article here for help: [**https://minnovation.com.au/knowledge-base/how-to-enable-conduit-for-a-user/**](https://minnovation.com.au/knowledge-base/how-to-enable-conduit-for-a-user/) {% endhint %} 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 V2 \/\/pub/v2 **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. **device 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. ### Publish Message V2 **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: #### Formatting the Payload The data array should be an array of Objects that are configured in the following key:value pair format: ```json data: [ { channelId : integer; // the channel identifier for the value value : number; // the value of the data (16 digit maximum length) } ] ``` {% hint style="warning" %} **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. {% endhint %} {% hint style="info" %} **Note:** AlphaX has a limit of 16 data channels per device. Should additional channels be required, we suggest splitting the data over 2 seperate data sources. {% endhint %} ### Example Usage Publish to mqtt.alphax.cloud #### Topic ``` xxxxxxxxxxxxxxxxxx/mydevice1234/pub/v2 ``` #### Message ```json "data": [ { "channelId": 1, "value": 462.467835 }, { "channelId": 255, "value": 3.976 } ] ```