DRAFT — Preliminary version, do not share. · Version préliminaire, ne pas partager.

Mises à jour du micrologiciel (OTA)

Téléversez une version de micrologiciel vers un type d'appareil, puis envoyez-la par voie hertzienne à un appareil ou à tous les appareils de ce type dans un registre. Fundamentum suit la mise à jour d'un parc appareil par appareil, et vous permet de l'annuler ou de la relancer en un seul appel.

Mise à jour du micrologiciel par lot : une version de micrologiciel et ses fichiers sont publiés sur un type d'appareil, un lot crée une commande de mise à jour du micrologiciel par appareil, chaque appareil télécharge et installe les fichiers puis signale sa progression, et chaque appareil passe de unassigned à pending, ongoing, puis success, failure ou cancel

Avant de commencer

Fonctionnement

Une mise à jour du micrologiciel est l'une des commandes intégrées de la plateforme, identifiée par le nom court firmware-update. Le micrologiciel est stocké sous forme de versions d'un type d'appareil. Lorsque vous envoyez la commande, l'appareil reçoit le name, l'identifier et la configuration de la version, ainsi qu'une URL de téléchargement présignée pour chacun de ses fichiers. Il télécharge les fichiers, les installe et signale sa progression.

Une commande unique cible un appareil. Un lot en cible plusieurs : une liste d'appareils, ou tous les appareils d'un type dans un registre. Chaque appareil d'un lot a l'un des six statuts suivants :

Statut Signification
unassigned Créée, pas encore transmise à l'appareil
pending En attente de livraison
ongoing L'appareil est en cours d'installation
success L'appareil a signalé un succès
failure L'appareil a signalé un échec
cancel Annulée avant la fin

1. Créer une version de micrologiciel

Une version possède un name d'affichage et un identifier unique au sein du type d'appareil. configuration est un JSON libre facultatif que l'appareil reçoit avec la mise à jour.

fun api v1 device-type store-version \
  --project-id <project-id> --device-type-id <device-type-id> \
  --body '{"name": "Firmware 2.4.0", "identifier": "2.4.0", "configuration": {"channel": "stable"}}'

Conservez l'id de la réponse : c'est votre <version-id>.

2. Téléverser les fichiers du micrologiciel

Demandez une URL de téléversement pour chaque fichier, puis téléversez-y le fichier :

fun api v1 device-type store-version-file \
  --project-id <project-id> --device-type-id <device-type-id> --version-id <version-id> \
  --body '{"file_name": "firmware-2.4.0.bin"}' --data-only

curl --upload-file firmware-2.4.0.bin "<upload_url>"

Pour vérifier ce que les appareils recevront, lisez la charge utile d'action de la version. Son tableau configuration_file_url contient une URL de téléchargement présignée pour chaque fichier :

fun api v1 device-type get-v1-projects-by-project-id-device-types-by-device-type-id-versions-by-version-id-action-payload \
  --project-id <project-id> --device-type-id <device-type-id> --version-id <version-id>

3. Mettre à jour un appareil

Demandez à Fundamentum de préparer la commande pour un appareil. La réponse contient la command (avec son id), les versions disponibles pour cet appareil et, lorsque l'appareil est joint via une passerelle, les gateways qui peuvent le relayer :

fun api v1 commands create-device-commands \
  --project-id <project-id> --short-name firmware-update --device-id <device-id>

Envoyez-la ensuite, en utilisant l'id de la commande et la version cible :

fun api v1 commands store-device-commands \
  --project-id <project-id> --short-name firmware-update --device-id <device-id> \
  --body '{"device_id": <device-id>, "command_id": <command-id>, "version_id": <version-id>}'

Ajoutez "gateway_id": <gateway-id> pour un appareil joint via une passerelle. Consultez Passerelles et sous-appareils. Suivez la commande avec fun api v1 commands list-device-commands --project-id <project-id> --device-id <device-id>.

4. Mettre à jour l'ensemble du parc

Envoyez la commande à tous les appareils d'un type dans un registre :

fun api v1 commands store-batch-command-by-device-type \
  --project-id <project-id> --registry-id <registry-id> \
  --short-name firmware-update --device-type-id <device-type-id> \
  --body '{"parameters": {"command_id": <command-id>, "version_id": <version-id>}}'

Pour cibler plutôt une sélection, utilisez store-batch-command-by-device-ids avec {"device_ids": [...], "parameters": {...}}.

5. Suivre le lot

# All batches of the registry: batch_id, command, commands_count, last_update
fun api v1 commands list-batch-commands --project-id <project-id> --registry-id <registry-id>

# Number of devices in each status
fun api v1 commands batch-command-report-report \
  --project-id <project-id> --registry-id <registry-id> --batch-id <batch-id>

# Per-device detail
fun api v1 commands list-batch-command-device-commands \
  --project-id <project-id> --registry-id <registry-id> --batch-id <batch-id>

Dans le Hub, la vue du lot affiche le même rapport sous forme de graphique et s'actualise automatiquement.

6. Annuler ou relancer

Les opérations par lot s'appliquent à tous les appareils se trouvant actuellement dans un statut donné. Le statut dans le chemin sélectionne les appareils, et le status dans le corps correspond à ce que vous voulez faire avec eux.

Annulez tout ce qui n'a pas démarré (exécutez-la une fois pour unassigned et une fois pour pending) :

fun api v1 commands update-batch-command-by-status \
  --project-id <project-id> --registry-id <registry-id> --batch-id <batch-id> --status pending \
  --body '{"command_name": "firmware-update", "status": "cancel", "message": "Cancelled by operator."}'

Relancez chaque appareil en échec :

fun api v1 commands update-batch-command-by-status \
  --project-id <project-id> --registry-id <registry-id> --batch-id <batch-id> --status failure \
  --body '{"command_name": "firmware-update", "status": "retry", "message": "Retried by operator."}'

Une nouvelle tentative génère de nouvelles URL de téléchargement. Pour effacer les entrées terminées du lot, utilisez delete-batch-command-by-status avec --status cancel ou --status failure. Les boutons Cancel all, Retry all et Clear all du Hub effectuent les mêmes appels.

Étapes suivantes