Tutoriel

Un jeton valide OAuth v2 Bearer est requis. Voir Authentification pour plus de détails.

Gestion des passerelles

Ajout d'une passerelle

L’exemple de cette section utilise les valeurs suivantes d’une passerelle :

Informations requises	Exemple
Nom de la passerelle	`ACME BS 1`
LRR UUID	`7076FF-024B0B030008`

Récupération d'un modèle de passerelle

La sélection d’un modèle de passerelle est obligatoire pour ajouter une passerelle. Vous pouvez récupérer un ID de modèle de passerelle en répertoriant les modèles de passerelle existants.

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
}

Extrayez l’ID du modèle de passerelle sélectionné à partir de la réponse.

Ajout de la passerelle

L’exemple suivant utilise l’ID du modèle de passerelle récupéré à l’étape précédente.

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

Récupération d'une RF region

La RF region de la passerelle doit être configurée. Vous pouvez récupérer une RF region en listant les RF regions existantes.

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
}

Extrayez le provID de la RF region sélectionnée à partir de la réponse.

Configuration de la RF region de la passerelle

La configuration de la RF region repose sur une commande asynchrone de la passerelle. Voir Mise à jour de la RF region d’une passerelle pour plus de détails.

Lister les passerelles

Vous pouvez répertorier toutes les passerelles. La liste des passerelles est paginée. La pagination basée sur un curseur est recommandée pour garantir de bonnes performances et aucune limitation du nombre de passerelles récupérées.

La pagination basée sur un curseur est une nouveauté de ThingPark Enterprise SaaS 8.1.3 / ThingPark Enterprise auto-hébergé 8.1.0

Récupération de la première page

Pour utiliser la pagination basée sur un curseur, la liste des passerelles doit être triée par 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="
    }
}

Le champ count indique le nombre total de passerelles. Il n’est renvoyé qu’avec la première page.

Si une deuxième page est disponible, more est défini sur true. La valeur cursors.last peut être utilisée pour récupérer la deuxième page comme décrit dans la section suivante.

Récupération des pages suivantes

La valeur cursors.last de la dernière page récupérée doit être renseignée dans le paramètre de requête pageAfter pour récupérer la page suivante.

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="
    }
}

Si une page suivante est disponible, more est défini sur true. La valeur cursors.last peut être utilisée pour récupérer la page suivante comme décrit dans cette section.

Récupération d’une passerelle

La ressource passerelle est récupérée à l’aide de l’UUID de la passerelle 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",
    ...
}

Récupération de l’historique de trafic d’une passerelle

Vous pouvez récupérer l’historique de trafic d’une passerelle à l’aide de l’UUID de la passerelle 7076FF-024B0B030008. L'exemple suivant récupère une agrégation quotidienne du trafic pour les 7 derniers jours dans le fuseau horaire Europe/Paris.

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
            }
        },
        ...
    ]
}

Liste des alarmes de passerelle

Vous pouvez répertorier toutes les alarmes de passerelle. La liste des alarmes est paginée. La pagination basée sur un curseur est recommandée pour garantir de bonnes performances et aucune limitation du nombre d’alarmes récupérées.

La pagination basée sur un curseur est une nouveauté de ThingPark Enterprise SaaS 8.1.3 / ThingPark Enterprise auto-hébergé 8.1.0

Récupération de la première page

Pour utiliser la pagination basée sur un curseur, la liste des alarmes doit être triée par Uid d’alarme.

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"
    }
}

Le champ count indique le nombre total d’alarmes. Il n’est renvoyé qu’avec la première page.

Si une deuxième page est disponible, more est défini sur true. La valeur cursors.last peut être utilisée pour récupérer la deuxième page comme décrit dans la section suivante.

Récupération des pages suivantes

La valeur cursors.last de la dernière page récupérée doit être renseignée dans le paramètre de requête pageAfter pour récupérer la page suivante.

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"
    }
}

Si une page suivante est disponible, more est défini sur true. La valeur cursors.last peut être utilisée pour récupérer la page suivante comme décrit dans cette section.

Exécution d’une commande d’administration de passerelle

note

Les commandes d’administration ne sont pas supportées par les passerelles utilisant le packet forwarder Basics Station de Semtech.

À propos des commandes d’administration de passerelle

Les tâches suivantes nécessitent l’exécution de commandes d’administration sur la passerelle :

Logiciel LRR
- Mettre à jour le logiciel LRR : POST /partners/mine/bss/{bsUid}/admins/upgrade
- Récupérer la version actuelle du logiciel LRR : GET /partners/mine/bss/{bsUid}/admins/swVersion
Cellule RF
- Redémarrer les communications montantes (uplink) et descendantes (downlink) de la cellule RF : POST /partners/mine/bss/{bsUid}/admins/rfcStart
- Arrêter les communications montantes (uplink) et descendantes (downlink) de la cellule RF : POST /partners/mine/bss/{bsUid}/admins/rfcStop
- Redémarrer la communication descendante (downlink) de la cellule RF : POST /partners/mine/bss/{bsUid}/admins/rfcDownlinkStop
- Récupérer l’état de la cellule RF : GET /partners/mine/bss/{bsUid}/admins/rfcStatus
Redémarrage de la passerelle
- Redémarrer : POST /partners/mine/bss/{bsUid}/admins/reboot
- Récupérer le temps de fonctionnement du système : GET /partners/mine/bss/{bsUid}/admins/systemUptime
Redémarrer le processus LRR
- Redémarrer le processus LRR : POST /partners/mine/bss/{bsUid}/admins/restart
- Récupérer le temps de fonctionnement du processus LRR : GET /partners/mine/bss/{bsUid}/admins/softwareUptime
Sauvegarde et restauration
- Sauvegarder le logiciel LRR actuel et la configuration : POST /partners/mine/bss/{bsUid}/admins/backup
- Restaurer le logiciel LRR actuel et la configuration : POST /partners/mine/bss/{bsUid}/admins/restore
- Récupérer la version de la sauvegarde : GET /partners/mine/bss/{bsUid}/admins/backupSwVersion
Analyse RF
- Lancer une analyse du spectre radio : POST /partners/mine/bss/{bsUid}/admins/scanRadio
- Annuler l’analyse du spectre radio : POST /partners/mine/bss/{bsUid}/admins/cancelRadioScan
- Récupérer l’état de l’analyse RF : GET /partners/mine/bss/{bsUid}/admins/scanRadioStatus
Emplacement et altitude
- Mettre à jour l’emplacement : POST /partners/mine/bss/{bsUid}/admins/updateLocation
- Récupérer l’emplacement : GET /partners/mine/bss/{bsUid}/admins/locationStatus
RF region
- Mettre à jour la RF region : POST /partners/mine/bss/{bsUid}/admins/updateRfRegion
- Récupérer la RF region : GET /partners/mine/bss/{bsUid}/admins/rfRegionStatus
Gain des antennes et atténuation du cable
- Mettre à jour le gain et l’atténuation du cable pour toutes les antennes : POST /partners/mine/bss/{bsUid}/admins/updateAntennasGainAndLoss
- Récupérer le gain et l’atténuation du cable de toutes les antennes : GET /partners/mine/bss/{bsUid}/admins/antennasGainAndLossStatus
Clés de déchiffrement de fine-timestamps
- Mettre à jour les clés de déchiffrement de fine-timestamps : POST /partners/mine/bss/{bsUid}/admins/updateFineTimestampKeys
- Récupérer les clés de déchiffrement de fine-timestamps : GET /partners/mine/bss/{bsUid}/admins/fineTimestampKeysStatus
Niveau de trace
- Mettre à jour la configuration des journaux : POST /partners/mine/bss/{bsUid}/admins/updateLog
- Récupérer la configuration des journaux : GET /partners/mine/bss/{bsUid}/admins/logStatus
Mot de passe de support
- Modifier le mot de passe de support : POST /partners/mine/bss/{bsUid}/admins/changeSupportPassword

Chaque point de terminaison d’API POST ci-dessus demande l’exécution d’une commande asynchrone sur la passerelle. Une réponse de succès indique que la commande est mise en file d’attente et sera exécutée prochainement. Une seule commande peut être mise en file d’attente à la fois pour une passerelle donnée, sauf avant sa connexion initiale où plusieurs commandes peuvent être mises en file d’attente pour finaliser la configuration. Dans ce cas, les commandes sont exécutées une par une après la connexion initiale de la passerelle. L’état de la dernière commande peut être interrogé en utilisant GET /partners/mine/bss/{bsUid}/admins/lastCmdStatus.

Chaque point de terminaison d’API GET ci-dessus déclenche l’exécution d’une commande synchrone sur la passerelle. Une réponse de succès indique que la commande a été exécutée avec succès et que le résultat est fourni dans le corps de la réponse.

À titre d’exemple, la section suivante décrit les étapes pour mettre à jour la RF region d’une passerelle. Toutes les autres commandes suivent le même schéma.

Mise à jour de la RF region d’une passerelle

L’exemple de cette section utilise le LRR UUID 7076FF-024B0B030008 et le provID de la RF region que vous souhaitez associer à la passerelle. Voir Récupération d’une RF region pour plus de détails.

Demande de mise à jour de la RF region

Vous devez demander l’exécution d’une commande asynchrone sur la passerelle afin de mettre à jour sa 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

Une réponse 200 OK indique que la commande asynchrone est mise en file d’attente et sera exécutée prochainement.

Interrogation de l’état de la mise à jour

Vous devez interroger l’état de la commande asynchrone tant qu’elle n’a pas atteint un état final.

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"
}

Le champ lastCmdCompletionStatus indique l’état de la dernière commande asynchrone :

PENDING : la commande est toujours dans la file d’attente, patientez et interrogez à nouveau l’état plus tard.
PROCESSING : la commande est en cours d’exécution sur la passerelle, patientez et interrogez à nouveau l’état plus tard.
COMPLETED : la commande est terminée avec succès, vous pouvez passer à l’étape suivante afin de vérifier que le résultat de la mise à jour de la RF region est réussi.
ERR_NOSTART : l’exécution de la commande ne peut pas être démarrée sur la passerelle après plusieurs tentatives (la passerelle n’est pas connectée ou autre cause), vous devez vérifier l’état de la connexion de la passerelle et relancer la mise à jour depuis le début.
ERR_EXEC : l’exécution de la commande a échoué sur la passerelle, vous devez diagnostiquer le problème à l’aide du champ lastCmdCompletionData et relancer la mise à jour depuis le début.
ERR_NOEND : l’exécution de la commande a été démarrée mais le résultat ne peut pas être récupéré après plusieurs tentatives, vous pouvez passer à l’étape suivante afin de vérifier le résultat de la mise à jour de la RF region et relancer la mise à jour depuis le début si nécessaire.

Récupération du résultat de la mise à jour de la RF region

Après l’achèvement de la commande, vous pouvez récupérer le résultat de la mise à jour de la RF region.

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)"
    }
}

Le champ completionStatus indique l’état d’achèvement de la commande synchrone exécutée pour récupérer les informations de la RF region actuelle :

COMPLETED : la commande est terminée avec succès et le résultat est également renvoyé. Si la commande asynchrone de mise à jour de la RF region a été terminée avec succès, le champ rfRegion.ID doit correspondre au provID de la RF region que vous souhaitiez associer à la passerelle.
ERR_NOSTART : l’exécution de la commande ne peut pas être démarrée sur la passerelle (la passerelle n’est pas connectée ou autre cause), vous devez vérifier l’état de la connexion de la passerelle et relancer la commande.
ERR_EXEC : l’exécution de la commande a échoué sur la passerelle, vous devez diagnostiquer le problème et relancer la commande.
ERR_NOEND : l’exécution de la commande a été démarrée mais le résultat ne peut pas être récupéré, vous devez diagnostiquer le problème et relancer la commande.

Gestion des passerelles​

Ajout d'une passerelle​

Récupération d'un modèle de passerelle​

Ajout de la passerelle​

Récupération d'une RF region​

Configuration de la RF region de la passerelle​

Lister les passerelles​

Récupération de la première page​

Récupération des pages suivantes​

Récupération d’une passerelle​

Récupération de l’historique de trafic d’une passerelle​

Liste des alarmes de passerelle​

Récupération de la première page​

Récupération des pages suivantes​

Exécution d’une commande d’administration de passerelle​

À propos des commandes d’administration de passerelle​

Mise à jour de la RF region d’une passerelle​

Demande de mise à jour de la RF region​

Interrogation de l’état de la mise à jour​

Récupération du résultat de la mise à jour de la RF region​

Gestion des passerelles

Ajout d'une passerelle

Récupération d'un modèle de passerelle

Ajout de la passerelle

Récupération d'une RF region

Configuration de la RF region de la passerelle

Lister les passerelles

Récupération de la première page

Récupération des pages suivantes

Récupération d’une passerelle

Récupération de l’historique de trafic d’une passerelle

Liste des alarmes de passerelle

Récupération de la première page

Récupération des pages suivantes

Exécution d’une commande d’administration de passerelle

À propos des commandes d’administration de passerelle

Mise à jour de la RF region d’une passerelle

Demande de mise à jour de la RF region

Interrogation de l’état de la mise à jour

Récupération du résultat de la mise à jour de la RF region