MyThings API Overview
Important prerequisite
You can start using the MyThings API only if you have a valid and active MyThings subscription. For new customers looking to subscribe to MyThings you can contact us here.
MyThings is a management platform that holds a set of powerful APIs which allows you to easily manage the sensors connected to your IoT network. MyThings gives u an overview of all sensors and their connection status with the install base. Link logical actions to the sensors, and your business processes will run smoother than ever. This way, IoT can truly bring added value to your company.
- Easy to manage IoT platforms
- Possible for any type of network
- Visualization and monetization of data
- Integration with your company's back-end processes
Technical info
MyThings API supports the following functionalities:
- Provisioning API's (Add, Delete, Update things)
- Downlink API's (Send data towards your LoRa things)
- Query API's (Get historical data from your things)
- Status API
- Stream data API
Integrate
CloudEngine provides MyThings inbound modules allowing transformation and enrichment on incoming IoT data flows, flexible outbound endpoints with HTTP and MQTT as well as integration with IoT platforms such as Microsoft Azure, SAP IoT Cloud and Waylay.
For more info on activation and start configuring this API, read more below.# MyThings API Introduction The MyThings integration on the EnCo platform covers two major functionalities:
- API’s to allow for an easy integration of the MyThings functionalities into you own application with a simple HTTP request.
- A CloudEngine inbound endpoint for an easy integration of the data generated by your LoRaWAN IoT devices in visual flows and scripts in CloudEngine.
MyThings API's for the following functionalities are exposed:
- Provisioning API's (Add, Delete, Update things)
- Downlink API's (Send data towards your LoRa things)
- Query API's (Get historical data from your things)
- Status API
Next to the API's above there is also a Stream data API and the Uplink data API.
Stream data API
In order to receive the real-time data from your things you need to setup a data stream towards your application endpoint in the Stream Definition setup on MyThings. For more info on stream data stream please check Stream data API or the MyThings user manual that is available via the MyThings portal. When linking your MyThings and EnCo account, please also note that a new Stream of type “CLOE” is automatically created on MyThings. This stream enables the usage of the MyThings inbound endpoint on CloudEngine.
Uplink data API
The Uplink data API will be available soon.
Getting Started
Introduction
You have some IoT Things? Do you have an account on MyThings and Enabling Company? Then you are ready to start using our MyThings API's! Below are some quick pointers on how to get started.
If you still need a device and/or account, you can obtain one using the links below:
- MyThings Account: https://mythings.proximus.be (please contact your sales or send a mail to iot@proximus.com in order to get access)
- Proximus API Solutions Account: https://market.enco.io
- Device catalogue: Please contact your sales or send a mail to iot@proximus.com in order to get the latest catalogue.
High Level Overview
Activating the MyThings API's for your existing MyThings account
Currently you can only use the MyThings API's if you have an existing MyThings account.
1.Create an account on the Proximus API Solutions marketplace and go to the MyThings API asset.
2. Subscribe to the Existing MyThings Plan.
3. You will receive an invitation mail from noreply@clearmedia.be with a link to connect your Enabling company account with your existing MyThings account.
Open link from mail
Please make sure that you open the link in the same browser (other tab) than where you have logged into the enco.io account.
Before linking the account
- Please make sure that the existing company you want to link is a main company and not a sub company.
- Please make sure that the MyThings user you use to link has a **superadmin **account.
- Please make sure that no other user has already linked to your company. The link can only be done once per main company.
Only press "Log in" once
When your login is correct, is a superadmin to for a main company that was not linked before it will take a few seconds to link the accounts. When the linking is done you will the screen below.
4. This will grant access to the Endpoint and API console, where you can try out the MyThings API's.
You can use the temporary API key from the console or the permanent one from the project/ token management (General API tokens).
You can test the API's via the API console. A curl example is provided here.
In the near future you will also be able to have access to the MyThings API's if you have no existing MyThings account. It will be possible to order a new MyThings account via the Marketplace.
Provisioning API's
The MyThings provisioning API's allow to manage your things (add, delete, update, …), your LoRa device addresses for ABP things and retrieve some thing provisioning information.
Base url: https://api.enco.io/mythings/1.1.0
Header | Value | Required |
---|---|---|
Authorization | Bearer <access token> | Yes |
Accept | application/json | Yes |
Content-type | application/json | Yes |
The access_token should be retrieved via the authentication API.
/things GET
/things POST
/things/{thingIdentifier} DELETE
/things/{thingIdentifier} GET
/things/{thingIdentifier} PUT
/things/{thingIdentifier}/deprovision DELETE
/things/{thingIdentifier}/provision POST
/things/{thingIdentifier}/tags PUT
/things/{thingIdentifier}/type GET
/things/{thingIdentifier}/{containerFriendlyName} DELETE
/basestations/{basestationId} PUT
/deviceaddress GET
/deviceaddress/assign PUT
/deviceaddress/reserve GET
/connectivityplans GET
/thingtypes GET
/vendors GET
/streamdefinitions GET
/streamdefinitions POST
/streamdefinitions PUT
/streamdefinitions DELETE
/things
GET /things
Description
Retrieve a list of things based on the given search criteria. All parameters are optional. If no parameters are defined all the things you own and all public things will be returned.
Parameters
Type | Name | Description | Schema |
---|---|---|---|
Query | isPublic optional |
isPublic | boolean |
Query | lastActivity optional |
lastActivity | string (date-time) |
Query | modifiedSince optional |
modifiedSince | string (date-time) |
Query | results optional |
results | integer (int32) |
Query | tags optional |
tags | < string > array(multi) |
Query | thingName optional |
thingName | string |
Responses
HTTP Code | Description | Schema |
---|---|---|
200 | OK | ThingResource |
Consumes
application/json
Produces
application/json
POST /things
Description
Create a new thing of any type and if needed provision it on the network.
Parameters
Type | Name | Description | Schema |
---|---|---|---|
Body | thingCreateRequest required |
thingCreateRequest | ThingCreateRequest |
Responses
HTTP Code | Description | Schema |
---|---|---|
200 | OK | ThingResource |
Consumes
application/json
Produces
application/json
Example
POST /things ABP
{
"connectivityType":"LORA.ABP",
"thingIdentifier":"1234ABCDABCD3333",
"companyId":77,
"thingName":"testmythingname",
"description":"mythingsdescription",
"isPublic":false,
"thingTypeId":33,
"longitude":"mythingslongitude",
"latitude":"mythingslatitude",
"locationFN1":"mythingsfn1",
"locationFN2":"mythingsfn1",
"connectivityPlan":"pxs-iot-cs/96-up-transactions-0-down",
"deviceAddress":"ABCd12AA",
"keys":{
"applicationSessionkeys":[
{"applicationSessionKey":"11111234123412341234123412341243","port":"1"}
],
"networkSessionKey":"44341234123412344444123412341241"},
"tags":["tag1","tag2","taggedyTagTag"],
"motionIndicator":"Vehicle speed"
}
POST /things OTAA
{
"connectivityType":"LORA.OTAA",
"thingIdentifier":"ABCDAB22ABCDABC2",
"companyId":162,
"thingName":"mythingname",
"description":"mythingsdescription",
"isPublic":false,
"thingTypeId":10,
"longitude":"mythingslongitude",
"latitude":"mythingslatitude",
"locationFN1":"mythingsfn1",
"locationFN2":"mythingsfn1",
"connectivityPlan":"pxs-iot-cs/288-up-transactions-24-down",
"keys":{
"applicationKey":"12341234123412341234123412341234",
"applicationEUI":"1234123412341234"
},
"motionIndicator":"Random"
}
POST /things ETHERNET (available soon)
{
"connectivityType":"ETHERNET",
"thingIdentifier":"ABCDAB22ABCDABC2",
"companyId":376,
"thingName":"mythingname",
"description":"mythingsdescription",
"isPublic":false,
"thingTypeId":24,
"longitude":"mythingslongitude",
"latitude":"mythingslatitude",
"locationFN1":"mythingsfn1",
"locationFN2":"mythingsfn2",
"serialNumber":"1234123412341234"
}
DELETE /things/{thingIdentifier}
Description
The thing is completely removed including a deprovisioning of the resource.
Parameters
Type | Name | Description | Schema |
---|---|---|---|
Path | thingIdentifier required |
thingIdentifier | string |
Responses
HTTP Code | Description | Schema |
---|---|---|
200 | OK |
Consumes
application/json
Produces
application/json
GET /things/{thingIdentifier}
Description
Get the details of a specific thing using his thing identifier as key.
Parameters
Type | Name | Description | Schema |
---|---|---|---|
Path | thingIdentifier required |
thingIdentifier | string |
Responses
HTTP Code | Description | Schema |
---|---|---|
200 | OK | ThingResource |
Consumes
application/json
Produces
application/json
PUT /things/{thingIdentifier}
Description
Get the details of a specific thing using its thing identifier as key.
Parameters
Type | Name | Description | Schema |
---|---|---|---|
Path | thingIdentifier required |
thingIdentifier | string |
Body | thingUpdateRequest required |
thingUpdateRequest | ThingUpdateRequest |
Responses
HTTP Code | Description | Schema |
---|---|---|
200 | OK | ThingResource |
Consumes
application/json
Produces
application/json
Example
PUT /things/{thingIdentifier} OTAA
{
"isPublic":false,
"thingName":"updatedThingName",
"description":"updatedDescription",
"tags":["tag1","tag2","tag3","tag4","tag5","tag6"],
"latitude":"2",
"longitude":"50",
"locationFN1":"updateFn1",
"locationFN2":"updateFn2",
"keysLoRaOTAA":{
"applicationKey":"55551234123412341234123412341234",
"applicationEUI":"4444123412344444"
}
}
PUT /things/{thingIdentifier} ABP
{
"isPublic":false,
"thingName":"updatedThingName",
"description":"updatedDescription",
"tags":["tag1","tag2","tag3","tag4","tag5","tag6"],
"latitude":"2",
"longitude":"50",
"locationFN1":"updateFn1",
"locationFN2":"updateFn2",
"keysLoRaABP":{
"applicationSessionkeys":[
{
"applicationSessionKey":"11111234123412341234123412341243",
"port":"1"
}
],
"networkSessionKey":"44341234123412344444123412341241"
}
}
PUT /things/{thingIdentifier} ABP (remove applicationSessionKeys)
{
"keysLoRaABP":{
"applicationSessionkeys":[{}]
}
}
PUT /things/{thingIdentifier} ETHERNET (available soon)
{
"isPublic":false,
"thingName":"ethernetDevice",
"description":"updateDescription",
"tags":["tag1","dummyTag","anotherTag","tag2","tag3"],
"latitude":"2",
"longitude":"50",
"locationFN1":"fn1",
"locationFN2":"fn2"
}
DELETE /things/{thingIdentifier}/deprovision
Description
Remove a thing from the network only. This only applies for LoRa things.
Parameters
Type | Name | Description | Schema |
---|---|---|---|
Path | thingIdentifier required |
thingIdentifier | string |
Responses
HTTP Code | Description | Schema |
---|---|---|
200 | OK | StatusMessageDTO |
Consumes
application/json
Produces
application/json
POST /things/{thingIdentifier}/provision
Description
Add a thing to the network only. This only applies for LoRa things.
Parameters
Type | Name | Description | Schema |
---|---|---|---|
Path | thingIdentifier required |
thingIdentifier | string |
Responses
HTTP Code | Description | Schema |
---|---|---|
200 | OK | StatusMessageDTO |
Consumes
application/json
Produces
application/json
PUT /things/{thingIdentifier}/tags
Description
Add a tag to a thing.
Parameters
Type | Name | Description | Schema |
---|---|---|---|
Path | thingIdentifier required |
thingIdentifier | string |
Body | tags required |
tags | < string > array |
Responses
HTTP Code | Description | Schema |
---|---|---|
200 | OK | ThingResource |
Consumes
application/json
Produces
application/json
Example
PUT /things/{thingIdentifier}/tags (single tag)
["dummyTag"]
**PUT /things/{thingIdentifier}/tags (multiple tags)
["tag0","tag1","tag3","tag4"]
GET /things/{thingIdentifier}/type
Parameters
Type | Name | Description | Schema |
---|---|---|---|
Path | thingIdentifier required |
thingIdentifier | string |
Responses
HTTP Code | Description | Schema |
---|---|---|
200 | OK | ThingContainerResource |
Consumes
application/json
Produces
application/json
DELETE /things/{thingIdentifier}/{containerFriendlyName}
Parameters
Type | Name | Description | Schema |
---|---|---|---|
Path | containerFriendlyName required |
containerFriendlyName | string |
Path | thingIdentifier required |
thingIdentifier | string |
Responses
HTTP Code | Description | Schema |
---|---|---|
200 | OK | StatusMessageDTO |
Consumes
application/json
Produces
application/json
/basestations
PUT /basestations/{basestationId}
Description
Add a longitude and latitude to a LoRa base station
Parameters
Type | Name | Description | Schema |
---|---|---|---|
Path | basestationId required |
basestationId | string |
Body | basestationUpdateRequest required |
basestationUpdateRequest | basestationUpdateRequest |
Responses
HTTP Code | Description | Schema |
---|---|---|
200 | OK | BaseStationResponse |
Consumes
application/json
Produces
application/json
Example
PUT /basestations/{id}
{
"companyId": 987,
"latitude": "50",
"locationName": "Wall street",
"longitude": "2"
}
/deviceaddress
GET /deviceaddress
Description
For LoRa ABP things only. It gives the next available device addresses that are in the state “reserved” for your company.
Parameters
Type | Name | Description | Schema |
---|---|---|---|
Query | companyId required |
companyId | integer (int32) |
Query | amount required |
amount | integer (int32) |
Responses
HTTP Code | Description | Schema |
---|---|---|
200 | OK | DeviceAddressResponse |
Consumes
application/json
Produces
application/json
PUT /deviceaddress/assign
Parameters
Type | Name | Description | Schema |
---|---|---|---|
Body | deviceAddressAssignRequest required |
deviceAddressAssignRequest | DeviceAddressAssignRequest |
Responses
HTTP Code | Description | Schema |
---|---|---|
200 | OK | DeviceAddressResponse |
Consumes
application/json
Produces
application/json
Example
PUT /deviceaddress/assign
{
"companyId": 987,
"devAddresses": [
"07FFF001"
]
}
GET /deviceaddress/reserve
Parameters
Type | Name | Description | Schema |
---|---|---|---|
Query | amount required |
amount | integer (int32) |
Query | companyId required |
companyId | integer (int32) |
Responses
HTTP Code | Description | Schema |
---|---|---|
200 | OK | DeviceAddressResponse |
Consumes
application/json
Produces
application/json
/connectivityplans
GET /connectivityplans
Responses
HTTP Code | Description | Schema |
---|---|---|
200 | OK | < ConnectivityPlanResult > array |
Consumes
application/json
Produces
application/json
/thingtypes
GET /thingtypes
Responses
HTTP Code | Description | Schema |
---|---|---|
200 | OK | < ThingTypeDTO > array |
Consumes
application/json
Produces
application/json
/vendors
GET /vendors
Responses
HTTP Code | Description | Schema |
---|---|---|
200 | OK | < VendorDTO > array |
Consumes
application/json
Produces
application/json
/streamdefinitions
GET /streamdefinitions/{streamDefinitionId}
Responses
HTTP Code | Description | Schema |
---|---|---|
200 | OK | < streamrequest> |
Consumes
application/json
Produces
application/json
createStreamDefinition
POST /streamdefinitions
Parameters
Type | Name | Description | Schema |
---|---|---|---|
Path | thingIdentifier required |
thingIdentifier | string |
Responses
HTTP Code | Description | Schema |
---|---|---|
200 | OK | < streamrequest> |
Consumes
application/json
Produces
application/json
Example
Make sure that value of property template has a backslash ( \ ) before every double-quote character ( " ). See below for a working example.
The "mutualAuth":true is available when it's activated by Proximus on company level. By default its not activated. POST /streamdefinitions
{
"active": false,
"autoLink": true,
"companyId": 987,
"contentType": "JSON",
"basicAuth": false,
"mutualAuth": false,
"name": "MyStream",
"template": "{\"timestamp\": \"%timestamp[yyyy-MM-dd HH:mm:ss.SSS]%\",\"company\": \"%companyname%\",\"macaddress\": \"%thingidentifier%\",\"container\": \"%container%\",\"location\": \"%locationfriendlyname1%\",\"value\": \"%value%\",\"description\": \"PirSensor\"}",
"type": "DECODED",
"url": "https://my.streaming.url"
}
PUT /streamdefinitions/{streamDefinitionId}
Responses
HTTP Code | Description | Schema |
---|---|---|
200 | OK | < streamrequest> |
Consumes
application/json
Produces
application/json
Example
PUT /streamdefinitions/{streamDefinitionId}
{
"active": true,
"headers":[
{
"key":"Content-Type",
"value":"application/json"
}
],
"password": "admin",
"userName": "admin"
}
DELETE /streamdefinitions
Responses
HTTP Code | Description | Schema |
---|---|---|
200 | OK | / |
Consumes
application/json
Produces
application/json
Downlink API's
The MyThings downlink API's allow to send data your LoRa things.
Base url: https://api.enco.io/mythings/1.1.0
Header | Value | Required |
---|---|---|
Authorization | Bearer <access token> | Yes |
Accept | application/json | Yes |
Content-type | application/json | Yes |
The access_token should be retrieved via the authentication API. See the Authentication page
/downlink POST
/downlink/template/{templateUid} POST
/configurationtemplates GET
/downlink
POST /downlink
Parameters
Type | Name | Description | Schema |
---|---|---|---|
Body | downlinkRequest required |
downlinkRequest | DownlinkRequest |
Responses
HTTP Code | Description | Schema |
---|---|---|
200 | OK | DownlinkResponse |
Consumes
application/json
Produces
application/json
Example
POST /downlink
{
"devEUI":"9999888877776666",
"fPort":"9",
"payload":"04FD20D9",
"encrypted":"0",
"ack": 1
}
POST /downlink/template/{templateUid}
Parameters
Type | Name | Description | Schema |
---|---|---|---|
Path | templateUid required |
templateUid | string |
Body | downlinkRequest required |
downlinkRequest | DownlinkRequest |
Responses
HTTP Code | Description | Schema |
---|---|---|
200 | OK | DownlinkResponse |
Consumes
application/json
Produces
application/json
Example
POST /downlink/template/{templateUid}
{
"thingIdentifiers":[
"BACBADBADADBADAD",
"AAAAAAAAAAAAAAAA"
]
}
/configurationtemplates
GET /configurationtemplates
Responses
HTTP Code | Description | Schema |
---|---|---|
200 | OK | ConfigurationTemplatesResponse |
Consumes
application/json
Produces
application/json
Query API's
The MyThings query API's allow your application to retrieve data from your things (historical data) and also from your base stations and business rules.
Pricing for the query API's can be found on the enco marketplace.
Base url: https://api.enco.io/mythings/1.1.0
Header | Value | Required |
---|---|---|
Authorization | Bearer <access token> | Yes |
Accept | application/json | Yes |
Content-type | application/json | No |
The access_token should be retrieved via the authentication API.
/things/{thingIdentifier}/locations GET
/things/{thingIdentifier}/logs/decoded GET
/things/{thingIdentifier}/logs/decoded/count GET
/things/{thingIdentifier}/logs/network GET
/things/{thingIdentifier}/logs/network/count GET
/things/{thingIdentifier}/type/{containerName}/values GET
/basestations GET
/basestations/{basestationId} GET
/businessrules GET
/businessrulestriggered GET
/businessrulestriggered/{businessRuleId} GET
/containerdefinitions GET
/things
GET /things/{thingIdentifier}/locations
Parameters
Type | Name | Description | Schema |
---|---|---|---|
Path | thingIdentifier required |
thingIdentifier | string |
Query | page optional |
page | integer (int32) |
Query | timeframe optional |
timeframe | integer (int32) |
Responses
HTTP Code | Description | Schema |
---|---|---|
200 | OK | PageResource«LocationHistory» |
Consumes
application/json
Produces
application/json
GET /things/{thingIdentifier}/logs/decoded
Parameters
Type | Name | Description | Schema |
---|---|---|---|
Path | thingIdentifier required |
thingIdentifier | string |
Query | page optional |
page | integer (int32) |
Query | timeframe optional |
timeframe | integer (int32) |
Responses
HTTP Code | Description | Schema |
---|---|---|
200 | OK | PageResource«SensorHistory» |
Consumes
application/json
Produces
application/json
GET /things/{thingIdentifier}/logs/decoded/count
Parameters
Type | Name | Description | Schema |
---|---|---|---|
Path | thingIdentifier required |
thingIdentifier | string |
Query | interval required |
interval | enum (HOURLY, DAILY, WEEKLY, MONTHLY) |
Responses
HTTP Code | Description | Schema |
---|---|---|
200 | OK | < CountResponse > array |
Consumes
application/json
Produces
application/json
GET /things/{thingIdentifier}/logs/network
Parameters
Type | Name | Description | Schema |
---|---|---|---|
Path | thingIdentifier required |
thingIdentifier | string |
Query | page optional |
page | integer (int32) |
Query | timeframe optional |
timeframe | integer (int32) |
Query | startTime optional |
startTime | string (date-time) |
Query | endTime optional |
endTime | string (date-time) |
Responses
HTTP Code | Description | Schema |
---|---|---|
200 | OK | PageResource«NetworkData» |
Consumes
application/json
Produces
application/json
GET /things/{thingIdentifier}/logs/network/count
Parameters
Type | Name | Description | Schema |
---|---|---|---|
Path | thingIdentifier required |
thingIdentifier | string |
Query | endTime optional |
endTime | string (date-time) |
Query | interval required |
interval | enum (HOURLY, DAILY, WEEKLY, MONTHLY) |
Query | startTime optional |
startTime | string (date-time) |
Responses
HTTP Code | Description | Schema |
---|---|---|
200 | OK | < CountResponse > array |
Consumes
application/json
Produces
application/json
GET /things/{thingIdentifier}/type/{containerName}/values
Parameters
Type | Name | Description | Schema |
---|---|---|---|
Path | containerName required |
containerName | string |
Path | thingIdentifier required |
thingIdentifier | string |
Query | endTime optional |
endTime | string (date-time) |
Query | results optional |
results | integer (int32) |
Query | startTime optional |
startTime | string (date-time) |
Responses
HTTP Code | Description | Schema |
---|---|---|
200 | OK | < ThingContainerValueResource > array |
Consumes
application/json
Produces
application/json
/basestations
GET /basestations
Responses
HTTP Code | Description | Schema |
---|---|---|
200 | OK | < BaseStationResponse > array |
Consumes
application/json
Produces
application/json
GET /basestations/{basestationId}
Parameters
Type | Name | Description | Schema |
---|---|---|---|
Path | basestationId required |
basestationId | string |
Responses
HTTP Code | Description | Schema |
---|---|---|
200 | OK | BaseStationResponse |
Consumes
application/json
Produces
application/json
/businessrules
GET /businessrules
Responses
HTTP Code | Description | Schema |
---|---|---|
200 | OK | ResponseEntity |
Consumes
application/json
Produces
application/json
GET /businessrulestriggered
Responses
HTTP Code | Description | Schema |
---|---|---|
200 | OK | < triggeredBusinessRule > array |
Consumes
application/json
Produces
application/json
GET /businessrulestriggered/{businessRuleId}
Parameters
Type | Name | Description | Schema |
---|---|---|---|
Path | businessRuleId required |
businessRuleId | integer (int32) |
Query | action optional |
action | string |
Query | containerName optional |
containerName | string |
Responses
HTTP Code | Description | Schema |
---|---|---|
200 | OK | < triggeredBusinessRule > array |
Consumes
application/json
Produces
application/json
/containerdefinitions
GET /containerdefinitions
Parameters
Type | Name | Description | Schema |
---|---|---|---|
Query | thingTypeName optional |
thingTypeName | string |
Responses
HTTP Code | Description | Schema |
---|---|---|
200 | OK | < ContainerDefinitionDTO > array |
Consumes
application/json
Produces
application/json
Status API
An API endpoint where the current MyThings status can be retrieved.
Base url: https://api.enco.io/mythings/1.1.0
Header | Value | Required |
---|---|---|
Authorization | Bearer <access token> | Yes |
Accept | application/json | Yes |
Content-type | application/json | No |
The access_token should be retrieved via the authentication API.
/status GET
/status
GET /status
Description
The overall status of the MyThings API.
Responses
HTTP Code | Description | Schema |
---|---|---|
200 | OK | UP/DOWN |
Consumes
application/json
Produces
application/json
Stream Definitions
1.Log into MyThings and go to the Settings / Stream Definitions menu
2.Create a new stream definition
Company: The company or sub company you want to configure the stream on.
Type: NETWORK/DECODED/LBS
Stream Name: This is a free field to identify the stream.
Stream URL: This needs to be a valid URL for the endpoint where you want to send the data.
Both HTTP and HTTPS is supported.
- The endpoint needs to return valid http status code (200, 404, 500…) and status message. The status message may not contain variable data (timestamp …) as that will put every failure in a separate line in the stream definition failure and make it hard to reprocess the failed data. (data with the same http status code and status message will be grouped in the stream definition failures).
- Proximus will monitor if incorrect URL’s are configured and can disable streams towards invalid or broken URL’s.
- If the HTTP(S) status code is not returned then there will be a timeout. The stream will be put on “Timeout” for 60 seconds and all data from the things that was send during those 60 seconds will be put in the “stream definition failures” and can be reprocessed manually.
Stream security: you can select “None”, “Basic Authentication” and on request a “Mutual Authentication” option can be enabled (this option is available as a professional service – please contact your sales – documentation on this option is not available here and can be found on MyThings in the documentation menu).
Headers: are optional based on application server header requirements.
IoT Connect
You can define 2 stream definitions per company.
- You can create network stream definition. The format is the Raw XML that we receive from our LoRa network.
- You can create a DECODED or LOCATION stream definition in XML, JSON or FREEFORM with selectable presets. The elements in the JSON depend on the ones that were selected.
- You can select which things are linked to the stream definitions. The thing to stream link can be set manually or automatically.
- You can give the stream a custom name.
Example network stream (XML):
<?xml version="1.0" encoding="UTF-8"?>
<DevEUI_uplink xmlns="http://uri.actility.com/lora">
<Time>2019-03-22T11:14:30.426+01:00</Time>
<DevEUI>0011223344000259</DevEUI>
<FPort>2</FPort>
<FCntUp>93473</FCntUp>
<ADRbit>1</ADRbit>
<MType>2</MType>
<FCntDn>27080</FCntDn>
<payload_hex>00</payload_hex>
<mic_hex>fd80eaf4</mic_hex>
<Lrcid>00000201</Lrcid>
<LrrRSSI>-95.000000</LrrRSSI>
<LrrSNR>6.000000</LrrSNR>
<SpFact>12</SpFact>
<SubBand>G0</SubBand>
<Channel>LC1</Channel>
<DevLrrCnt>2</DevLrrCnt>
<Lrrid>FF0107A5</Lrrid>
<Late>0</Late>
<LrrLAT>00.223259</LrrLAT>
<LrrLON>00.972714</LrrLON>
<Lrrs>
<Lrr>
<Lrrid>FF0107A5</Lrrid>
<Chain>0</Chain>
<LrrRSSI>-95.000000</LrrRSSI>
<LrrSNR>6.000000</LrrSNR>
<LrrESP>-95.973228</LrrESP>
</Lrr>
<Lrr>
<Lrrid>FF010624</Lrrid>
<Chain>0</Chain>
<LrrRSSI>-107.000000</LrrRSSI>
<LrrSNR>-20.000000</LrrSNR>
<LrrESP>-127.043213</LrrESP>
</Lrr>
</Lrrs>
<CustomerID>100000000</CustomerID>
<CustomerData>{"alr":{"pro":"LORA/Generic","ver":"1"}}</CustomerData>
<ModelCfg>0</ModelCfg>
<InstantPER>0.000000</InstantPER>
<MeanPER>0.012488</MeanPER>
<DevAddr>061008D0</DevAddr>
<TxPower>1.000000</TxPower>
<NbTrans>1</NbTrans>
</DevEUI_uplink>
Example Decoded stream (JSON):
{
"companyName": "Proximus Demo",
"thingName": "Temperature and humidity",
"thingVersion": "1",
"thingType": "Temperature and humidity",
"vendor": "NKE",
"latitude": "",
"longitude": "",
"description": "",
"locationFriendlyName1": "Brussels Proximus towers",
"locationFriendlyName2": "",
"containerFriendlyName": "Temperature",
"container": "0x0402.0x0000.0.m2m",
"value": "23.79",
"postfix": "°",
"timestamp": "1487187830340",
"DevEUI": "70B3D5E75E000259",
"DevAddr": "5E000259",
"FPort": "6",
"Fcntup": "22843",
"Ackbit": "",
"Adrbit": "1",
"Fcntdn": "6386",
"Lrcid": "00000201",
"Lrrrssi": "-83.000000",
"Lrrsnr": "8.000000",
"Spfact": "12",
"Subband": "G1",
"Channel": "LC2",
"Dvlrrcnt": "2",
"Lrrid": "004A0362",
"Customerid": "100000136",
"Customerdata": "{\"loc\":{\"lat\":\"50.860191\",\"lon\":\"4.358177\"},\"alr\":{\"pro\":\"WECO/TPHU\",\"ver\":\"1\"}}",
"Modelcfg": "0",
"Batterylevel": "",
"Batterytime": "",
"margin": "",
"payload": "0402000029094b"
}
In order to see some real messages easily you can use an online service like https://hookbin.com and create and endpoint url there. If you fill in that endpoint URL as the stream URL on MyThings, then the data will be send to there where it is visualised. Services like hookbin only keep the URL valid for a very limited time. After you have some example data, please disable the stream or change the URL to your valid server endpoint URL so that the system does not generate stream error mails
Aggregated Containers:
You have the option to receive the decoded data in 2 ways. (per container OR aggregated).
If the aggregated option is disabled, then the decode stream will send data on thing container level (one POST per container). If a thing sends one message and it has multiple containers (example: temperature/humidity/battery) then multiple POST’s will be done.
Example:
Message 1
{
"companyName": "Proximus Demo",
"DevEUI": "0E7E3464061004A2",
"container": "temperature",
"containerfriendlyName": "humidity",
"value": "22.93",
"locationFriendlyName1": null,
"timestamp": "19/09/2019 12:23:48"
}
Message 2
{
"companyName": "Proximus Demo",
"DevEUI": "0E7E3464061004A2",
"container": "humidity",
"containerfriendlyName": "humidity",
"value": "52",
"locationFriendlyName1": null,
"timestamp": "19/09/2019 12:23:48"
}
If the aggregated option is enabled, then the decode stream will group all containers in 1 message. If a thing sends one message and it has multiple containers (example: temperature/humidity/battery) then only 1 POST’s will be done.
Example:
{
"companyName": "Proximus Demo",
"DevEUI": "0E7E3464061004A2",
"containers": [
{
"container": "temperature",
"containerfriendlyName": "temperature",
"value": "22.93",
"postfix": "°C"
},
{
"container": "humidity",
"containerfriendlyName": "humidity",
"value": "52",
"postfix": "%"
}
],
"locationFriendlyName1": null,
"timestamp": "19/09/2019 12:23:49"
}
MyThings inbound endpoint for CloudEngine
When linking your MyThings and EnCo account, and if subscribed to the EnCo CloudEngine, you will get access to two new inbound endpoints on CloE:
- MyThings - Data: receives sensor data from devices in your MyThings account. Incoming data can be filtered with tags so that visual flows or scripts can be triggered based on deviceEUI, thing type, company name or any tag associated to your things on MyThings.
- MyThings - Things: receives updates about things such as new things, removed things, provisioned/deprovisioned things. Incoming events can be filtered with tags so that visual flows or scripts can be triggered based on event type, thing identifier, thing type, company name or any tag associated to your things on MyThings.
Documentation about these inbound endpoints are available from within CloudEngine, by clicking on the question marks of each respective endpoint, as shown below:
When selecting The MyThings - Data as input, the stream setup will be done automatically in the MyThings stream definitions.
Definitions
ApplicationSessionKeyResource
Name | Description | Schema |
---|---|---|
applicationSessionKey optional |
[ApplicationSessionKey must be 32 characters] | string |
port optional |
string |
BaseStationResponse
Name | Schema |
---|---|
basestationId optional |
string |
basestationName optional |
string |
companyId optional |
integer (int32) |
companyName optional |
string |
firmware optional |
string |
lastRestart optional |
string (date-time) |
location optional |
Location |
state optional |
enum (CONNECTED, NEVERCONNECTED, CONNECTIONLOST) |
Basestationupdaterequest
Name | Schema |
---|---|
companyId optional |
integer (int32) |
locationName optional |
string |
longitude optional |
string |
latitude optional |
string |
Company
Name | Schema |
---|---|
companyId optional |
integer (int32) |
companyid optional |
integer (int32) |
name optional |
string |
ConnectivityPlan
Name | Schema |
---|---|
assignedthings optional |
integer (int32) |
connectivitytype optional |
enum (LORA, ETHERNET) |
id optional |
string |
name optional |
string |
ConnectivityPlanResult
Name | Schema |
---|---|
companyName optional |
string |
connectivityPlans optional |
< ConnectivityPlan > array |
subscriberId optional |
string |
Container
Name | Schema |
---|---|
container optional |
string |
containerId optional |
integer (int32) |
name optional |
string |
type optional |
string |
ContainerDefinitionDTO
Name | Schema |
---|---|
connectivityType optional |
string |
container optional |
string |
name optional |
string |
thingTypeName optional |
string |
vendor optional |
string |
ConfigurationTemplatesResponse
Name | Schema |
---|---|
name optional |
string |
uid optional |
string |
CountResponse
Name | Schema |
---|---|
count optional |
integer (int32) |
endTime optional |
string |
startTime optional |
string |
Data
Name | Schema |
---|---|
accuracy optional |
number (double) |
altRadius optional |
number (double) |
altitude optional |
number (double) |
latitude optional |
number (double) |
locRadius optional |
number (double) |
longitude optional |
number (double) |
time optional |
integer (int64) |
ts optional |
integer (int64) |
type optional |
string |
value optional |
string |
DeviceAddressAssignRequest
Name | Schema |
---|---|
companyId optional |
integer (int32) |
devAddresses optional |
< string > array |
DeviceAddressResponse
Name | Schema |
---|---|
amount optional |
integer (int32) |
companyId optional |
integer (int32) |
devAddresses optional |
< string > array |
DownlinkRequest
Name | Description | Schema |
---|---|---|
devEUI required |
string | |
fPort required |
1-255 | string |
payload required |
HEX with even bytes (max 50 bytes) | string |
encrypted optional |
0/1 | integer (int32) |
ack optional |
0/1 | integer (int32) |
DownlinkRequestWithTemplate
Name | Description | Schema |
---|---|---|
downlinkConfigTemplateRequest required |
1-255 | string |
DownlinkResponse
Name | Schema |
---|---|
code optional |
string |
errors optional |
< Error > array |
message optional |
string |
Error
Name | Schema |
---|---|
field optional |
string |
message optional |
string |
Link
Name | Schema |
---|---|
href optional |
string |
rel optional |
string |
templated optional |
boolean |
Location
Name | Schema |
---|---|
altitude optional |
integer (int32) |
estimatedradius optional |
integer (int32) |
latitude optional |
string |
locationFN1 optional |
string |
locationFN2 optional |
string |
locationtype optional |
string |
longitude optional |
string |
name optional |
string |
timestamp optional |
string (date-time) |
LocationHistory
Name | Schema |
---|---|
company optional |
Company |
count optional |
integer (int32) |
created_on optional |
string (date-time) |
data optional |
< Data > array |
date optional |
integer (int64) |
sensor optional |
Sensor |
updated_on optional |
integer (int64) |
Lrr
Name | Schema |
---|---|
lrrESP optional |
string |
lrrRSSI optional |
string |
lrrSNR optional |
string |
lrrid optional |
string |
NetworkData
Name | Schema |
---|---|
ackBit optional |
string |
adrBit optional |
string |
appSKey optional |
string |
battery optional |
string |
channel optional |
string |
companyId optional |
integer (int32) |
companyName optional |
string |
createdOn optional |
string (date-time) |
customerData optional |
string |
customerID optional |
string |
deliveryFailedCause1 optional |
string |
deliveryFailedCause2 optional |
string |
deliveryFailedCause3 optional |
string |
deliveryStatus optional |
string |
devAddr optional |
string |
devEUI optional |
string |
devLrrCnt optional |
string |
fcntDn optional |
string |
fcntUp optional |
string |
fport optional |
string |
late optional |
string |
lrcid optional |
string |
lrrLAT optional |
string |
lrrLON optional |
string |
lrrRSSI optional |
string |
lrrSNR optional |
string |
lrrid optional |
string |
lrrs optional |
< Lrr > array |
mType optional |
string |
margin optional |
string |
mic_hex optional |
string |
modelCfg optional |
string |
payload_hex optional |
string |
spFact optional |
string |
subBand optional |
string |
time optional |
integer (int64) |
timeStr optional |
string |
type optional |
string |
PageResource«LocationHistory»
Name | Schema |
---|---|
content optional |
< LocationHistory > array |
first optional |
boolean |
last optional |
boolean |
links optional |
< Link > array |
number optional |
integer (int32) |
numberOfElements optional |
integer (int32) |
size optional |
integer (int32) |
sort optional |
Sort |
totalElements optional |
integer (int64) |
totalPages optional |
integer (int32) |
PageResource«NetworkData»
Name | Schema |
---|---|
content optional |
< NetworkData > array |
first optional |
boolean |
last optional |
boolean |
links optional |
< Link > array |
number optional |
integer (int32) |
numberOfElements optional |
integer (int32) |
size optional |
integer (int32) |
sort optional |
Sort |
totalElements optional |
integer (int64) |
totalPages optional |
integer (int32) |
PageResource«SensorHistory»
Name | Schema |
---|---|
content optional |
< SensorHistory > array |
first optional |
boolean |
last optional |
boolean |
links optional |
< Link > array |
number optional |
integer (int32) |
numberOfElements optional |
integer (int32) |
size optional |
integer (int32) |
sort optional |
Sort |
totalElements optional |
integer (int64) |
totalPages optional |
integer (int32) |
ResponseEntity
Name | Schema |
---|---|
body optional |
object |
statusCode optional |
enum (100, 101, 102, 103, 200, 201, 202, 203, 204, 205, 206, 207, 208, 226, 300, 301, 302, 303, 304, 305, 307, 308, 400, 401, 402, 403, 404, 405, 406, 407, 408, 409, 410, 411, 412, 413, 414, 415, 416, 417, 418, 419, 420, 421, 422, 423, 424, 426, 428, 429, 431, 451, 500, 501, 502, 503, 504, 505, 506, 507, 508, 509, 510, 511) |
statusCodeValue optional |
integer (int32) |
Sensor
Name | Schema |
---|---|
active optional |
boolean |
locationName optional |
string |
mac optional |
string |
name optional |
string |
sensorId optional |
integer (int32) |
type optional |
string |
SensorGroup
Name | Schema |
---|---|
sensorGroupId optional |
integer (int32) |
sensorGroupName optional |
string |
SensorHistory
Name | Schema |
---|---|
clusterName optional |
string |
company optional |
Company |
container optional |
Container |
count optional |
integer (int32) |
data optional |
< Data > array |
date optional |
integer (int64) |
location optional |
Location |
sensor optional |
Sensor |
sensorgroup optional |
SensorGroup |
totalCount optional |
integer (int32) |
Sort
Type : object
StatusMessageDTO
Name | Schema |
---|---|
message optional |
string |
status optional |
string |
TechnologyDetails
Name | Schema |
---|---|
activationType optional |
string |
deviceAddress optional |
string |
keysLoRaABP optional |
ThingKeysLoRaABP |
keysLoRaOTAA optional |
ThingKeysLoRaOTAA |
networkReady optional |
boolean |
provisioned optional |
boolean |
ThingContainerResource
Name | Schema |
---|---|
connectivityType optional |
string |
containers optional |
< Container > array |
thingType optional |
string |
thingTypeVersion optional |
string |
vendor optional |
string |
vendorReference optional |
string |
ThingContainerValueResource
Name | Schema |
---|---|
container optional |
string |
thingType optional |
string |
timestamp optional |
integer (int64) |
value optional |
string |
ThingCreateRequest
Name | Description | Schema |
---|---|---|
companyId required |
[CompanyId may not be null] | integer (int32) |
connectivityType required |
[ConnectivityType may not be null, ConnectivityType may not be blank, ConnectivityType can only be of type 'LORA.ABP', 'LORA.OTAA' or 'ETHERNET'] | enum (LORA.ABP, LORA.OTAA, ETHERNET) |
description optional |
string | |
isPublic optional |
boolean | |
latitude optional |
string | |
locationFN1 optional |
string | |
locationFN2 optional |
string | |
longitude optional |
string | |
tags optional |
< string > array | |
thingName optional |
string | |
motionIndicator optional |
Only for LoRa Things with LBS enabled. Near static, Walking speed, Vehicle speed, Random | string |
thingTypeId required |
[ThingTypeId may not be null] | integer (int32) |
ThingKeysLoRaABP
Name | Description | Schema |
---|---|---|
applicationSessionkeys optional |
< ApplicationSessionKeyResource > array | |
networkSessionKey required |
[NetworkSessionKey may not be null, NetworksKey must be 32 characters] | string |
ThingKeysLoRaOTAA
Name | Description | Schema |
---|---|---|
applicationEUI required |
[ApplicationEUI may not be null, ApplicationEUI must be 16 characters] | string |
applicationKey required |
[ApplicationKey may not be null, ApplicationKey must be 32 characters] | string |
ThingResource
Name | Description | Schema |
---|---|---|
companyId optional |
integer (int32) | |
companyName optional |
string | |
connectivityPlan optional |
string | |
connectivityType optional |
string | |
description optional |
string | |
insertionDate optional |
string (date-time) | |
iotProduct optional |
string | |
isPublic optional |
boolean | |
lastModifiedDate optional |
string (date-time) | |
lastlocation optional |
Location | |
motionIndicator optional |
string | |
tags optional |
< string > array | |
technologyDetails optional |
TechnologyDetails | |
thingId optional |
integer (int32) | |
thingIdentifier required |
[{javax.validation.constraints.NotNull.message}] | string |
thingKeysLoRaABP optional |
ThingKeysLoRaABP | |
thingKeysLoRaOTAA optional |
ThingKeysLoRaOTAA | |
thingName optional |
string | |
thingType optional |
string | |
vendor optional |
string |
ThingTypeDTO
Name | Schema |
---|---|
connectivityType optional |
string |
name optional |
string |
vendor optional |
string |
vendorReference optional |
string |
version optional |
integer (int32) |
ThingUpdateRequest
Name | Description | Schema |
---|---|---|
companyId optional |
Company ID of the thing | integer (int32) |
connectivityPlan optional |
string | |
description optional |
Description of the thing | string |
deviceAddress optional |
[DeviceAddress must be 8 characters] | string |
isPublic optional |
Public flag of the thing Example : false |
boolean |
keysLoRaABP optional |
ThingKeysLoRaABP | |
keysLoRaOTAA optional |
ThingKeysLoRaOTAA | |
latitude optional |
Latitude of the thing location | string |
locationFN1 optional |
Location friendly name one of the thing location | string |
locationFN2 optional |
Location friendly name two of the thing location | string |
longitude optional |
Longitude of the thing location | string |
motionIndicator optional |
string | |
tags optional |
Tags of the thing | < string > array |
thingName optional |
Name of the thing | string |
thingTypeId optional |
ThingType ID of the thing | integer (int32) |
VendorDTO
Name | Schema |
---|---|
name optional |
string |
rule
Name | Description | Schema |
---|---|---|
action optional |
string | |
email optional |
string | |
name required |
[{javax.validation.constraints.NotNull.message}] | string |
operator required |
[{javax.validation.constraints.NotNull.message}] | string |
operator2 optional |
string | |
parameter1 optional |
string | |
parameter2 optional |
string | |
templateName optional |
string | |
threshold required |
[{javax.validation.constraints.NotNull.message}] | number (double) |
threshold2 optional |
number (float) | |
timeToReset optional |
integer (int32) | |
timeToWait required |
[{javax.validation.constraints.NotNull.message}] | integer (int32) |
triggerOnce required |
[{javax.validation.constraints.NotNull.message}] | boolean |
thing
Name | Schema |
---|---|
name optional |
string |
thingIdentifier optional |
string |
thingType optional |
string |
triggeredBusinessRule
Name | Schema |
---|---|
businessRuleDTO optional |
rule |
businessRuleId optional |
integer (int32) |
company optional |
string |
timestamp optional |
integer (int64) |
triggeredByDTO optional |
triggeredBy |
triggeredBy
Name | Schema |
---|---|
thingGroupName optional |
string |
triggeredContainer optional |
Container |
triggeredThingDTO optional |
thing |
value optional |
string |
streamrequest
Name | Schema |
---|---|
active required |
string |
autoLink required |
string |
basicAuth required |
string |
companyId required |
string |
contentType required |
string |
mutualAuth required |
string |
type required |
string |
url required |
string |