API Reference

RAN Provider REST APIs provide direct data access to Base Station information for use in external monitoring and reporting. An API key is required to authenticate API usage. If you have not received an API key, please email your request to support@senetco.com or call the technical support phone number shown on support@senetco.com.

Base Station Provisioning API

The Base Station Provisioning API is designed to allow a customer to provision a set of Base Stations. This is similar to the bulk provisioning workflow provided by the UI and allows them to setup a Base Station before deploying it. They can enter basic provisioning information such as; eui, serial number, Base Station type, ISM Band, and classification.

Resource URL

https://api.senetco.io/rest/integration/bstn/provision

HTTP Method

POST

Parameters

None

Request Body(JSON)

Parameter Description Required Default Value Allowed Values
data An array containing all the Base Stations you wish to provision. See Base Station object section below Yes A correctly formatted JSON Array

Base Station Object

Parameter Description Required Default Value Allowed Values
eui The IEEE EUI-64 identifier for the LoRa Base Station. Yes A valid hexadecimal string
model The Base Station model ID (See table below) Yes A valid Base Station model
serialNum The Base Station serial number whose format matches the format supported by the given model Yes A valid Base Station serial number that matches the Base Station model serial number format.
classification The classification ID of the Base Station (See table below) Yes A valid Base Station classification
ismBandName A valid ISM band name to assign to the Base Station (See table below) Yes A valid ISM band name
tags Text identifiers added to a Base Station to assist in grouping and filtering No A comma separate list of tags

Base Station Models

Model Model ID Serial Number Format Example Serial Number
Arduino Yun/Tian ARDUINO_YUN 0xXXXXXXXXXXXX 0x01234567890A
Gemtek Indoor Femto GEMTEK_PICO XXXXXXXXXXXXXXX 1234567890ABCDE
Kerlink iFemtoCell KERLINK_PICO XXXXXXXXX F0F0F0F0F
Kerlink Wirnet iBTS 8 KERLINK_IBTS_8 ATFXXXXXX ATFF0F0F0
Kerlink Wirnet iBTS 64 KERLINK_IBTS_64 ATFXXXXXX ATFF0F0F0
Kerlink Wirnet iBTS Compact KERLINK_IBTS_16 ATFXXXXXX ATFF0F0F0
Kerlink Wirnet Station KERLINK_IOTS 0xXXXXXXX 0x0F0F0F0
Laird Sentrius LAIRD_SENTRIUS 0xXXXXXXXXXXXX 0x0123456789AB
MultiTech Conduit MULTITECH_CONDUIT XXXXXXXX F0F0F0F0
MultiTech Conduit 16 IP67 MULTITECH_CONDUIT_16_IP67 XXXXXXXX F0F0F0F0
MultiTech Conduit AP MULTITECH_CONDUIT_AP XXXXXXXX F0F0F0F0
MultiTech Conduit IP67 MULTITECH_CONDUIT_IP67 XXXXXXXX F0F0F0F0
Semtech Packet Forwarder SEMTECH_PKT_FORWARDER XXXXXXXXXXXXX... 1234567890ABCDEF
Tektelic KONA 8 TEKTELIC_KONA_8 TXXXXXXX_XXXXXXXXX T0123456_7890ABCDE
Tektelic KONA 16 Macro TEKTELIC_KONA_16 TXXXXXXX_XXXXXXXXX T0123456_7890ABCDE
Tektelic KONA 64 Mega TEKTELIC_KONA_64 TXXXXXXX_XXXXXXXXX T0123456_7890ABCDE
Tektelic KONA Micro Indoor TEKTELIC_KONA_MICRO_INDOOR TXXXXXXX_XXXXXXXXX T0123456_7890ABCDE

Base Station Classification

Classification Classification ID Description
Community COMMUNITY This classification identifies base stations that are used by the community. This is typically given to base stations used by developers.
Consumer CONSUMER This classification identifies consumer grade base stations (i.e. MultiTech Conduit).
Enterprise ENTERPRISE This classification identifies enterprise grade base stations.
Service Provider SERVICE_PROVIDER This classification identifies service provider grade base stations.

ISM Band Names

ISM Band ISM Band ID
US 902-928MHz US902-928:Default
US 902-928+700MHz US902-928+700:Default
EU 863-870MHz EU863-870:Default
India 865-867MHz India865-867:Default
India 865-867MHzAlt1 India865-867Alt1:Default
AU 915-928MHz AU915-928:Default
AS 923MHz AS923:Default

Response

Field Description Description
jobid ID of the currently executing Base Station provisioning job. Can be used with the base station task status API
responseMsg The response message from the server indicating if the job was started
serverId The id of the server processing the request
statusCode The status of the job being correctly started

HTTP Response Codes

Code Reason Description
200 Success Request has been successfully processed
403 Authorization Failure Access to this resource has been rejected due to an authorization issue.
400 Bad Request Invalid request due to insufficient or malformed parameters.

Example request:

{
    "data": [
        {
            "eui" : "FAFFFFFFFFFF0000",
            "serialNum" : "TF000000_000000001",
            "classification" : "SERVICE_PROVIDER",
            "ismBandName" : "EU863-870:Default",
            "model" : "TEKTELIC_KONA_64"
        },
        {
            "eui" : "FAFFFFFFFFFF0001",
            "serialNum" : "F1F3F2F1",
            "classification" : "CONSUMER",
            "ismBandName" : "US902-928:Default",
            "model" : "MULTITECH_CONDUIT"
        },
        {
            "eui" : "FAFFFFFFFFFF0002",
            "serialNum" : "0x0F0F0F3",
            "classification" : "COMMUNITY",
            "ismBandName" : "AU915-928:Default",
            "model" : "KERLINK_IOTS"
        },
        {
            "eui" : "FAFFFFFFFFFF0003",
            "serialNum" : "1234567890ABCDEF4",
            "classification" : "ENTERPRISE",
            "ismBandName" : "India865-867:Default",
            "model" : "SEMTECH_PKT_FORWARDER"
        },
        {
            "eui" : "FAFFFFFFFFFF0004",
            "serialNum" : "TF000000_000000005",
            "classification" : "ENTERPRISE",
            "ismBandName" : "AS923:Default",
            "model" : "TEKTELIC_KONA_8"
        }
    ]

}

Example Success Response:

{
    "jobId": "BstnMgmtJobReq:90000",
    "responseMsg": "BstnMgmtJobReq job starting now: Tue Dec 17 12:16:50 EST 2019",
    "serverId": "networkserver:OnPrem:172.18.0.1:8081",
    "statusCode": 200
}

Curl Example

curl -X POST \
  https://api.senetco.io/rest/integration/bstn/provision \
  -H 'Authorization: <your API key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "data": [
        {
            "eui" : "FAFFFFFFFFFF0000",
            "serialNum" : "TF000000_000000001",
            "classification" : "SERVICE_PROVIDER",
            "ismBandName" : "EU863-870:Default",
            "model" : "TEKTELIC_KONA_64"
        },
        {
            "eui" : "FAFFFFFFFFFF0001",
            "serialNum" : "F1F3F2F1",
            "classification" : "CONSUMER",
            "ismBandName" : "US902-928:Default",
            "model" : "MULTITECH_CONDUIT"
        },
        {
            "eui" : "FAFFFFFFFFFF0002",
            "serialNum" : "0x0F0F0F3",
            "classification" : "COMMUNITY",
            "ismBandName" : "AU915-928:Default",
            "model" : "KERLINK_IOTS"
        },
        {
            "eui" : "FAFFFFFFFFFF0003",
            "serialNum" : "1234567890ABCDEF4",
            "classification" : "ENTERPRISE",
            "ismBandName" : "India865-867:Default",
            "model" : "SEMTECH_PKT_FORWARDER"
        },
        {
            "eui" : "FAFFFFFFFFFF0004",
            "serialNum" : "TF000000_000000005",
            "classification" : "ENTERPRISE",
            "ismBandName" : "AS923:Default",
            "model" : "TEKTELIC_KONA_8"
        }
    ]

}'

Base Station Deploy API

The Base Station Deploy API is designed to allow deployment of a Base Station dynamically post install. This API allows information about the Base Station deployment to be updated without using the web application. The information that can be updated includes, location, height, radius, address, and name.

Note

A Base Station must be created through the provisioning workflow, if the Base Station wasn't provisioned this way, the network administrator's support team should be contacted. If a Base Station was previously deployed, subsequent deployments will override previously provided information.

Resource URL

https://api.senetco.io/rest/integration/bstn/deploy

HTTP Method

POST

Parameters

Parameter Description Required Default Value Allowed Values
eui The IEEE EUI-64 identifier for the LoRa Base Station. Yes Hexadecimal String

Request Body(JSON)

Parameter Description Required Default Value Allowed Values
address The street address of the site No A valid street address
city The city of the site No A valid city name
stateProvince The state or province of the site No A valid state or province
postalCode The postal code of the site No A valid postal code
name The name of the site No N/A
latitude The latitude of the site in decimal degrees Yes A non-zero value between 90 and -90
longitude The longitude of the site in decimal degrees Yes A non-zero value between 180 and -180
height The height above ground level of the top of the antenna in feet Yes A value greater than 0
radius The radius of the sites range in miles Yes A value greater than 0

Curl Example

curl -X POST \
  'https://api.senetco.io/rest/integration/bstn/deploy?eui=FEFFFFFFFFFF0001' \
  -H 'Authorization: <your api key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "address": "100 Market Street",
    "city": "Portsmouth",
    "stateProvince": "NH",
    "postalCode": "03801",
    "name": "Provisioned BSTN",
    "latitude": 44.071568,
    "longitude": -70.762245,
    "height": 100,
    "radius": 10
}'

Example request:

{
    "address": "100 Market Street",
    "city": "Portsmouth",
    "stateProvince": "NH",
    "postalCode": "03801",
    "name": "Provisioned BSTN",
    "latitude": 44.071568,
    "longitude": -70.762245,
    "height": 100,
    "radius": 10
}

Response

Code Reason Description
200 Success Request has been successfully processed
403 Authorization Failure Access to this resource was rejected due to an authorization failure
400 Bad Request Invalid request due to insufficient or malformed parameters
404 Base Station or File Not Found Indicates that the given Base Station EUI doesn't exist

Example Success Response:

{
    "message": "Success!"
}

Base Station Status API

The Base Station Status API returns detailed information for a set of Base Stations. This may include details about the Base Station like model type, version and uptime as well as current connection information.

There are 2 status sources supported by this API, that are selected using the required parameter.

Resource URL

https://api.senetco.io/rest/integration/bstn/details

Parameters

Parameter Name Description Required Default Value Allowed Values
eui The IEEE EUI-64 identifier for the Base Station. Used to limit the returned data to a specific EUI. No
status The type of status data to use as a source.
Alert=Retrieve Base Stations only with open alerts.
Any=Retrieve Base Stations with or without open alerts
Yes alert, any
fields A comma separated list of fields names to return in the data set. Used to return a smaller subset of data than the default.
Supported Fields:
"status, lastContact,lastPacket,name,model,ismBandName,version,uptime,radius,antennaHeight,alertLevel,deltaTime,address,"
"location,gpsLocation,gpsAltitude"
No All Fields Any combination of the supported fields

Field Descriptions

Field Name Description
status An object containing a color to indicate visual status, a "connIssues" string that describes the network connection state, and an alertCount
lastContact The date of the last communication from the Base Station to the Network Server
lastPacket The date when the last packet was received from the Base Station
name The name of the Base Station
model The model type of the Base Station
ismBandName The ISM Band radio frequency name assigned to the Base Station
version The firmware version installed on the Base Station
uptime The total time the Base Station has been active in seconds
radius The radius of the Base Station's Viewshed in miles
height The position height of the Base Station's Viewshed in feet. This is used to determine potential signal obstruction by intervening terrain.
alertLevel The alert configuration for the Base Station See Alerts for more details
deltaTime The time difference between a Base Station's current time and the Network Server's current time
address The address set for Base Station's associated Site
location An object containing the latitude and longitude set for the Base Station
gpsLocation An object containing a GPS obtained latitude and longitude if the Base Station supports GPS
gpsAltitude The GPS altitude, in meters, of the Base Station if the Base Station supports GPS

Curl Examples

Status for Base Stations with open alerts.

curl -H "authorization: <API_KEY_TO_USE>" -X POST "https://api.senetco.io/rest/integration/bstn/details?status=alert" 

Status for a specific Base Station with open alerts.

curl -H "authorization: <API_KEY_TO_USE>" -X POST "https://api.senetco.io/rest/integration/bstn/details?status=alert&eui=AAAAAAAAAAAAAAAA"

Status for Base Stations with or without open alerts.

curl -H "authorization: <API_KEY_TO_USE>" -X POST "https://api.senetco.io/rest/integration/bstn/details?status=any"

Status for a Base Station with or without open alerts, only return fields "status" and "lastContact".

curl -H "authorization: <API_KEY_TO_USE>" -X POST "https://api.senetco.io/rest/integration/bstn/details?status=any&eui=AAAAAAAAAAAAAAAA&fields=status,lastContact"

Response Examples

For a single Base Station all fields returned:

{
   "data":[
      {
         "eui":"AAAAAAAAAAAAAAAA",
         "status":{
            "color":"orange",
            "connIssues":"Connection Issues: No SSH",
            "alertCount":1
         },
         "lastContact":1550691020270,
         "lastPacket":1550691080252,
         "name":"Sample BSTN",
         "model":"MultiTech Conduit AP",
         "ismBandName":"US902-928:Default",
         "version":"02_04_04",
         "uptime":30187974,
         "radius":10,
         "antennaHeight":15.01,
         "alertLevel":"Level 1",
         "deltaTime":41,
         "location":{
            "latitude":43.083412,
            "longitude":-70.77599
         },
         "gpsLocation":{
            "latitude":"43.07851",
            "longitude":"-70.7583"
         },
         "gpsAltitude":"32.16134"
      }
   ]
}

Multiple Base Stations with only the "status" and "lastContact" fields returned:

{
   "data":[
      {
         "eui":"AAAAAAAAAAAAAAAA",
         "status":{
            "color":"orange",
            "connIssues":"Connection Issues: No SSH",
            "alertCount":1
         },
         "lastContact":1550691020270
      },
      {
         "eui":"BBBBBBBBBBBBBBBB",
         "status":{
            "color":"red",
            "connIssues":"No Issues",
            "alertCount":2
         },
         "lastContact":1550691020354
      }
   ]
}