Tutorial

A valid OAuth v2 Bearer token is required. See Authentication for more details.

Managing base stations

Adding a base station

The example in this section uses the following values of a base station:

Required Information	Example
BS name	`ACME BS 1`
LRR UUID	`7076FF-024B0B030008`

Retrieving a base station model

The selection of a base station model is mandatory to add a base station. You can retrieve a base station model ID by listing the existing base station models.

GET /thingpark/wireless/rest/partners/mine/bsProfiles HTTP/1.1
Authorization: Bearer ...
Accept: application/json
Cookie: JSESSIONID=gcn1wPKxdUPUW6yh8aPsAiwY.twa; GLOBALTWA=0

HTTP/1.1 200 OK
Content-Type: application/json

{
    "briefs": [
        {
            "commercialName": "Macro V1.5",
            "vendor": {
                "name": "Kerlink",
                "commercialName": "Kerlink",
                "commercialDescription": "Supplier of Internet of Things infrastructures deployments.",
                "ID": "kerlink"
            },
            "ID": "KERL/WIR2.1",
            "defaultIsmBands": [
                {
                    "name": "EU 863-870MHz ISM Band",
                    "ID": "eu868"
                },
                {
                    "name": "US 902-928MHz ISM Band",
                    "ID": "us915"
                }
            ]
        },
        ...
    ],
    "more": false
}

Extract the ID of the selected base station model from the response.

Adding the base station

The following example uses the base station model ID retrieved in the previous step.

POST /thingpark/wireless/rest/partners/mine/bss HTTP/1.1
Authorization: Bearer ...
Content-Type: application/json
Accept: application/json
Cookie: JSESSIONID=gcn1wPKxdUPUW6yh8aPsAiwY.twa; GLOBALTWA=0

{
    "lrrUUID": "7076FF-024B0B030008",
    "model": {
        "ID": "KERL/IBTS.1"
    },
    "name": "ACME BS 1",
    "bsSecurity": {
        "type": "IPSEC_X509"
    }
}

HTTP/1.1 201 Created
Location: /thingpark/wireless/rest/partners/139/bss/1222

Retrieving a RF region

The RF region of the base station must be configured. You can retrieve a RF region by listing the existing RF regions.

GET /thingpark/wireless/rest/partners/mine/rfRegions HTTP/1.1
Authorization: Bearer ...
Accept: application/json
Cookie: JSESSIONID=gcn1wPKxdUPUW6yh8aPsAiwY.twa; GLOBALTWA=0

HTTP/1.1 200 OK
Content-Type: application/json

{
    "briefs": [
        {
            "commercialName": "EU 863-870MHz (8 channels)",
            "commercialDescription": "This 8-channels RF Region applies to any region where the use of the 863-870 MHz ISM radio spectrum is compliant with the ETSI EN300.220 standard.",
            "commercialChangelog": "",
            "provID": "EU868_8channels.172",
            "version": 1,
            "logo": "/thingpark/wireless/rest/resources/files/logo/rFRegion/172",
            "href": "/thingpark/wireless/rest/partners/139/rfRegions/172"
        },
        ...
    ],
    "more": false
}

Extract the provID of the selected RF region from the response.

Configuring the base station RF region

The configuration of the RF region relies on a base station asynchronous command. See Updating the RF region of a base station for more details.

Listing the base stations

You can list all the base stations. The list of base stations is paginated. The cursor-based pagination is recommended to ensure good performances and no limitation in the number of retrieved base stations.

Cursor-based pagination is new in ThingPark Enterprise SaaS 8.1.3 / self-hosted ThingPark Enterprise 8.1.0

Retrieving the first page

In order to use the cursor-based pagination, the base station list must be sorted by LRR ID.

GET /thingpark/wireless/rest/partners/mine/bss?sort=lrrID%2Casc HTTP/1.1
Authorization: Bearer ...
Accept: application/json
Cookie: JSESSIONID=gcn1wPKxdUPUW6yh8aPsAiwY.twa; GLOBALTWA=0

HTTP/1.1 200 OK
Content-Type: application/json

{
    "briefs": [
        {
            "name": "ACME BS 1",
            "model": {
                "commercialName": "Macro V1.5",
                "logo": "/thingpark/wireless/rest/resources/files/logo/baseStationProfile/5"
            },
            "lrrID": "10009534",
            "lrrUUID": "7076FF-024B0B030008",
            "state": "ACTIVE",
            ...
            "href": "/thingpark/wireless/rest/partners/139/bss/1222"
        },
        ...
    ],
    "more": true,
    "now": 1556209037421,
    "count": 5016,
    "cursors": {
        "last": "eyJscnJJRCI6IjEwMDA5ODA0In0="
    }
}

The count indicates the total number of base stations. It is only returned with the first page.

If a second page is available, more is set to true. The cursors.last value can be used to retrieve the second page as described in the next section.

Retrieving the subsequent pages

The cursors.last value of the last retrieved page must be set in the pageAfter query parameter to retrieve the next page.

GET /thingpark/wireless/rest/partners/mine/bss?sort=lrrID%2Casc&pageAfter=eyJscnJJRCI6IjEwMDA5ODA0In0%3D HTTP/1.1
Authorization: Bearer ...
Accept: application/json
Cookie: JSESSIONID=gcn1wPKxdUPUW6yh8aPsAiwY.twa; GLOBALTWA=0

HTTP/1.1 200 OK
Content-Type: application/json

{
    "briefs": [
        {
            "name": "ACME BS 101",
            "model": {
                "commercialName": "Macro V1.5",
                "logo": "/thingpark/wireless/rest/resources/files/logo/baseStationProfile/5"
            },
            "lrrID": "10010397",
            "lrrUUID": "7076FF-024B0B031118",
            "state": "ACTIVE",
            ...
            "href": "/thingpark/wireless/rest/partners/139/bss/1462"
        },
        ...
    ],
    "more": true,
    "now": 1556209037421,
    "count": null,
    "cursors": {
        "last": "eyJscnJJRCI6IjEwMDEwNTI3In0="
    }
}

If a next page is available, more is set to true. The cursors.last value can be used to retrieve the next page as described in this section.

Retrieving a base station

The base station resource is retrieved using the base station's UUID 7076FF-024B0B030008.

GET /thingpark/wireless/rest/partners/mine/bss/u7076FF-024B0B030008 HTTP/1.1
Authorization: Bearer ...
Accept: application/json
Cookie: JSESSIONID=gcn1wPKxdUPUW6yh8aPsAiwY.twa; GLOBALTWA=0

HTTP/1.1 200 OK
Content-Type: application/json

{
    "now": 1556274131027,
    "occContext": {
        "version": 0,
        "lastUpdate": 1546598395000,
        "who": "John Doe"
    },
    "name": "ACME BS 1",
    "lrrID": "10009534",
    "lrrUUID": "7076FF-024B0B030008",
    "identificationMode": "LRR_UUID",
    "staticAddress": null,
    "customerAdminData": null,
    "state": "ACTIVE",
    ...
}

Retrieving the traffic history of a base station

You can retrieve the traffic history of a base station using the base station's UUID 7076FF-024B0B030008. The following example retrieves a daily aggregation of the traffic for the last 7 days in the Europe/Paris timezone.

GET /thingpark/wireless/rest/partners/mine/bss/u7076FF-024B0B030008/frames?duration=P7D&step=P1D&timezone=Europe/Paris HTTP/1.1
Authorization: Bearer ...
Accept: application/json
Cookie: JSESSIONID=gcn1wPKxdUPUW6yh8aPsAiwY.twa; GLOBALTWA=0

HTTP/1.1 200 OK
Content-Type: application/json

{
    "now": 1560257258301,
    "briefs": [
        {
            "timestamp": 1559959200000,
            "up": {
                "count": 241,
                "size": 5726,
                "countOnTime": 241,
                "sizeOnTime": 5726,
                "countLate": 0,
                "sizeLate": 0
            },
            "dw": {
                "count": 3,
                "size": 0,
                "countSent": 3,
                "sizeSent": 0,
                "countFailed": 0,
                "sizeFailed": 0
            }
        },
        {
            "timestamp": 1559970000000,
            "up": {
                "count": 239,
                "size": 5664,
                "countOnTime": 239,
                "sizeOnTime": 5664,
                "countLate": 0,
                "sizeLate": 0
            },
            "dw": {
                "count": 2,
                "size": 0,
                "countSent": 2,
                "sizeSent": 0,
                "countFailed": 0,
                "sizeFailed": 0
            }
        },
        ...
    ]
}

Listing the base station alarms

You can list all the base station alarms. The list of alarms is paginated. The cursor-based pagination is recommended to ensure good performances and no limitation in the number of retrieved alarms.

Cursor-based pagination is new in ThingPark Enterprise SaaS 8.1.3 / self-hosted ThingPark Enterprise 8.1.0

Retrieving the first page

In order to use the cursor-based pagination, the alarm list must be sorted by alarm Uid.

GET /thingpark/wireless/rest/partners/mine/bss/alarms?sort=alarmUid%2Casc HTTP/1.1
Authorization: Bearer ...
Accept: application/json
Cookie: JSESSIONID=gcn1wPKxdUPUW6yh8aPsAiwY.twa; GLOBALTWA=0

HTTP/1.1 200 OK
Content-Type: application/json

{
    "briefs": [
        {
            "ID": 102,
            "alarmUid": "5b1f81e7a1ae4234a037be11",
            "bs": {
                "name": "ACME BS 1",
                "lrrID": "10009534"
            },
            ...
            "href": "/thingpark/wireless/rest/partners/139/bss/1222/alarms/5b1f81e7a1ae4234a037be11"
        },
        ...
    ],
    "more": true,
    "count": 304,
    "cursors": {
        "last": "eyJhbGFybVVpZCI6IjViMWY4MWU3YTFhZTQyMzRhMDM3Y2QzNyJ9"
    }
}

The count indicates the total number of alarms. It is only returned with the first page.

If a second page is available, more is set to true. The cursors.last value can be used to retrieve the second page as described in the next section.

Retrieving the subsequent pages

The cursors.last value of the last retrieved page must be set in the pageAfter query parameter to retrieve the next page.

GET /thingpark/wireless/rest/partners/mine/bss/alarms?sort=alarmUid%2Casc&pageAfter=eyJhbGFybVVpZCI6IjViMWY4MWU3YTFhZTQyMzRhMDM3Y2QzNyJ9 HTTP/1.1
Authorization: Bearer ...
Accept: application/json
Cookie: JSESSIONID=gcn1wPKxdUPUW6yh8aPsAiwY.twa; GLOBALTWA=0

HTTP/1.1 200 OK
Content-Type: application/json

{
    "briefs": [
        {
            "ID": 110,
            "alarmUid": "5b1f81e7a1ae4234a037d092",
            "bs": {
                "name": "ACME BS 101",
                "lrrID": "10010397"
            },
            ...
            "href": "/thingpark/wireless/rest/partners/139/bss/1462/alarms/5b1f81e7a1ae4234a037d092"
        },
        ...
    ],
    "more": true,
    "count": null,
    "cursors": {
        "last": "eyJhbGFybVVpZCI6IjViMWY4MWU3YTFhZTQyMzRhMDM3ZTlhMiJ9"
    }
}

If a next page is available, more is set to true. The cursors.last value can be used to retrieve the next page as described in this section.

Executing a base station administrative command

note

Administrative commands are not supported by base stations using Semtech's Basics Station packet forwarder.

About base station administrative commands

The following tasks require to execute administrative commands on the base station:

LRR software
- Upgrade the LRR software: POST /partners/mine/bss/{bsUid}/admins/upgrade
- Retrieve the current LRR software version: GET /partners/mine/bss/{bsUid}/admins/swVersion
RF cell
- Restart the RF cell uplink and downlink communication: POST /partners/mine/bss/{bsUid}/admins/rfcStart
- Stop the RF cell uplink and downlink communication: POST /partners/mine/bss/{bsUid}/admins/rfcStop
- Restart the RF cell downlink communication: POST /partners/mine/bss/{bsUid}/admins/rfcDownlinkStop
- Retrieve the RF cell status: GET /partners/mine/bss/{bsUid}/admins/rfcStatus
Reboot base station
- Reboot: POST /partners/mine/bss/{bsUid}/admins/reboot
- Retrieve the system uptime: GET /partners/mine/bss/{bsUid}/admins/systemUptime
Restart LRR process
- Restart the LRR process: POST /partners/mine/bss/{bsUid}/admins/restart
- Retrieve the LRR process uptime: GET /partners/mine/bss/{bsUid}/admins/softwareUptime
Backup and restore
- Backup the current LRR software and configuration: POST /partners/mine/bss/{bsUid}/admins/backup
- Restore the current LRR software and configuration: POST /partners/mine/bss/{bsUid}/admins/restore
- Retrieve the backup version: GET /partners/mine/bss/{bsUid}/admins/backupSwVersion
RF scan
- Start an analysis of the radio spectrum: POST /partners/mine/bss/{bsUid}/admins/scanRadio
- Cancel the analysis of the radio spectrum: POST /partners/mine/bss/{bsUid}/admins/cancelRadioScan
- Retrieve the RF scan status: GET /partners/mine/bss/{bsUid}/admins/scanRadioStatus
Location and altitude
- Update the location: POST /partners/mine/bss/{bsUid}/admins/updateLocation
- Retrieve the location: GET /partners/mine/bss/{bsUid}/admins/locationStatus
RF region
- Update the RF region: POST /partners/mine/bss/{bsUid}/admins/updateRfRegion
- Retrieve the RF region: GET /partners/mine/bss/{bsUid}/admins/rfRegionStatus
Antennas gain and cable loss
- Update the gain and cable loss for all antennas: POST /partners/mine/bss/{bsUid}/admins/updateAntennasGainAndLoss
- Retrieve gain and cable loss of all antennas: GET /partners/mine/bss/{bsUid}/admins/antennasGainAndLossStatus
Fine-timestamp decryption keys
- Update the fine-timestamps decryption keys: POST /partners/mine/bss/{bsUid}/admins/updateFineTimestampKeys
- Retrieve the fine-timestamps decryption keys: GET /partners/mine/bss/{bsUid}/admins/fineTimestampKeysStatus
Trace level
- Update the log configuration: POST /partners/mine/bss/{bsUid}/admins/updateLog
- Retrieve the log configuration: GET /partners/mine/bss/{bsUid}/admins/logStatus
Support password
- Change the support password: POST /partners/mine/bss/{bsUid}/admins/changeSupportPassword

Each above POST API endpoint asks for the execution of an asynchronous command on the base station. A success response indicates that the command is queued and will be executed soon. Only one command can be queued at once for a given base station, except before its initial connection where several commands can be queued to finalize the configuration. In this case the commands are executed one by one after the initial connection of the base station. The status of the last command can be polled using GET /partners/mine/bss/{bsUid}/admins/lastCmdStatus.

Each above GET API endpoint triggers the execution of a synchronous command on the base station. A success response indicates that the command has been successfully executed and the result is provided in the response body.

As an example, the next section describes the steps to update the RF region of a base station. All other commands follow the same pattern.

Updating the RF region of a base station

The example in this section uses the LRR UUID 7076FF-024B0B030008 and the provID of the RF region you want to associate with the base station. See Retrieving a RF region for more details.

Asking for the RF region update

You need to ask for the execution of an asynchronous command on the base station in order to update its RF region.

POST /thingpark/wireless/rest/partners/mine/bss/u7076FF-024B0B030008/admins/updateRfRegion HTTP/1.1
Authorization: Bearer ...
Content-Type: application/json
Accept: application/json
Cookie: JSESSIONID=gcn1wPKxdUPUW6yh8aPsAiwY.twa; GLOBALTWA=0

{
    "rfRegionID": "EU868_8channels.172"
}

HTTP/1.1 200 OK

A 200 OK response indicates that the asynchronous command is queued and will be executed soon.

Polling the status of the update

You need to poll the status of the asynchronous command as long as it has not reached a final status.

GET /thingpark/wireless/rest/partners/mine/bss/u7076FF-024B0B030008/admins/lastCmdStatus HTTP/1.1
Authorization: Bearer ...
Accept: application/json
Cookie: JSESSIONID=gcn1wPKxdUPUW6yh8aPsAiwY.twa; GLOBALTWA=0

HTTP/1.1 200 OK
Content-Type: application/json

{
    "now": 1764690641557,
    "lastCmdRequestDate": 1764678984000,
    "lastCmdType": "UPDATE_RF_REGION",
    "lastCmdData": " -E -C EU868_8channels.172 -T rfregion -H s1_a1_b1",
    "lastCmdID": 1922,
    "lastCmdCompletionStatus": "COMPLETED",
    "lastCmdCompletionDate": 1764678984000,
    "lastCmdCompletionData": "\n#command completed\n0"
}

The lastCmdCompletionStatus field indicates the status of the last asynchronous command:

PENDING: The command is still in the queue, wait and poll the status again later.
PROCESSING: The command is currently executing on the base station, wait and poll the status again later.
COMPLETED: The command is successfully completed, you can go to the next step in order to check that the result of the RF region update is successful.
ERR_NOSTART: The execution of the command cannot be started on the base station after several retries (the base station is not connected or other cause), you need to check the connection status of the base station and retry the update from the beginning.
ERR_EXEC: The execution of the command failed on the base station, you need to troubleshoot the problem using the lastCmdCompletionData field and retry the update from the beginning.
ERR_NOEND: The execution of the command was started but the result cannot be retrieved after several retries, you can go to the next step in order to check the result of the RF region update and retry the update from the beginning if needed.

Retrieving the result of the RF region update

After the completion of the command, you can retrieve the result of the RF region update.

GET /thingpark/wireless/rest/partners/mine/bss/u7076FF-024B0B030008/admins/rfRegionStatus HTTP/1.1
Authorization: Bearer ...
Accept: application/json
Cookie: JSESSIONID=gcn1wPKxdUPUW6yh8aPsAiwY.twa; GLOBALTWA=0

HTTP/1.1 200 OK
Content-Type: application/json

{
    "completionStatus": "COMPLETED",
    "rfRegion": {
        "ID": "EU868_8channels.172",
        "version": 1,
        "name": "EU 863-870MHz (8 channels)"
    }
}

The completionStatus field indicates the completion status of the synchronous command executed to retrieve the current RF region information:

COMPLETED: The command is successfully completed and the result is also returned. If the RF region update asynchronous command was successfully completed, the rfRegion.ID should match the provID of the RF region you wanted to associated with the base station.
ERR_NOSTART: The execution of the command cannot be started on the base station (the base station is not connected or other cause), you need to check the connection status of the base station and retry the command.
ERR_EXEC: The execution of the command failed on the base station, you need to troubleshoot the problem and retry the command.
ERR_NOEND: The execution of the command was started but the result cannot be retrieved, you need to troubleshoot the problem and retry the command.

Managing base stations​

Adding a base station​

Retrieving a base station model​

Adding the base station​

Retrieving a RF region​

Configuring the base station RF region​

Listing the base stations​

Retrieving the first page​

Retrieving the subsequent pages​

Retrieving a base station​

Retrieving the traffic history of a base station​

Listing the base station alarms​

Retrieving the first page​

Retrieving the subsequent pages​

Executing a base station administrative command​

About base station administrative commands​

Updating the RF region of a base station​

Asking for the RF region update​

Polling the status of the update​

Retrieving the result of the RF region update​

Managing base stations

Adding a base station

Retrieving a base station model

Adding the base station

Retrieving a RF region

Configuring the base station RF region

Listing the base stations

Retrieving the first page

Retrieving the subsequent pages

Retrieving a base station

Retrieving the traffic history of a base station

Listing the base station alarms

Retrieving the first page

Retrieving the subsequent pages

Executing a base station administrative command

About base station administrative commands

Updating the RF region of a base station

Asking for the RF region update

Polling the status of the update

Retrieving the result of the RF region update