Bibliothèque MCU

Fundamentum Edge MCU C est une bibliothèque C portable qui connecte des appareils à microcontrôleur à Fundamentum. Vous branchez votre propre code HTTP, MQTT, de chiffrement et d'horloge au moyen de hooks, et la bibliothèque prend en charge le protocole Fundamentum. Cette page vous montre comment l'ajouter à votre micrologiciel et exécuter le flux de travail de base.

Composants Edge : le daemon Linux, la bibliothèque MCU et l'agent de redirection de ports

Ce que vous obtenez

C99, sans extensions de compilateur.
Aucune allocation dynamique : la bibliothèque fonctionne dans un tampon que vous fournissez.
Plusieurs contextes indépendants et réentrants, pour des tâches RTOS ou des threads.
Licence Apache-2.0. Dépendances incluses : coreJSON (MIT) et nanopb (Zlib).

Fonctionnalité	Description	Macro de désactivation dans `include/fundamentum_edge/config.h`
Provisionnement	Consulter le registre d'un appareil en stock	`EDGE_CFG__USE_PROVISIONING`
Actions	Recevoir et répondre aux actions	`EDGE_CFG__USE_ACTIONS`
Mise à jour du micrologiciel	Recevoir les demandes de mise à jour du micrologiciel	`EDGE_CFG__USE_FIRMWARE_UPDATE`
Heartbeat	Signaler l'état de santé de l'appareil	`EDGE_CFG__USE_HEARTBEAT`
États	Publier les états de l'appareil	`EDGE_CFG__USE_STATES`
Télémétrie	Publier la télémétrie	`EDGE_CFG__USE_TELEMETRY`

Avant de commencer

Un compilateur C99, CMake et just pour compiler la bibliothèque.
Un client HTTP (uniquement si vous utilisez le provisionnement), un client MQTT avec TLS, le hachage SHA-256 et la signature RSA sur votre plateforme.
Un appareil provisionné et sa clé privée. Consultez Provisionnement.

1. Ajouter la bibliothèque à votre micrologiciel

Choisissez une méthode d'intégration :

Méthode	Procédure
Sous-module Git	`git submodule add git@bitbucket.org:amotus/fundamentum-edge-mcu-c.git vendor/fundamentum-edge-mcu-c`, puis ajoutez les sources à votre compilation
Copie des sources	Copiez `src/`, `include/` et `vendor/` dans votre projet
Bibliothèque statique	Exécutez `just build-release` et liez `build/Release/libfundamentum-edge-mcu-c.a`

2. Implémenter les hooks

Les hooks sont les fonctions que la bibliothèque appelle sur votre plateforme. Implémentez ceux dont les fonctionnalités activées ont besoin :

Hook	Requis lorsque
`edge_hook_time_get`	Toujours (heure Unix actuelle)
`edge_hook_crypto_hash_buffer`	Toujours (SHA-256)
`edge_hook_crypto_sign_digest`	Toujours (signature RS256 pour le JWT)
`edge_hook_mqtt_publish_message`	Toujours
`edge_hook_http_send_request`	Le provisionnement est activé
`edge_hook_action_handle_incoming_request`	Les actions sont activées
`edge_hook_firmware_update_handle_incoming_request`	La mise à jour du micrologiciel est activée
`edge_hook_log_handler`	`EDGE_CFG__LOG_LEVEL` est supérieur à `EDGE_LOG_LEVEL__NONE`

Dans l'autre sens, transmettez chaque message MQTT reçu par votre client à la bibliothèque avec edge_feed_mqtt_message.

3. Exécuter le flux de travail

#include <fundamentum_edge.h>

edge_ctx_t *ctx = NULL;
uint8_t edge_buffer[EDGE_CTX_BUFFER_SIZE_HINT] = {0};
my_hook_ctx_t hook_ctx = {my_http_client, my_mqtt_client};
edge_error_t err = edge_ctx_init(&ctx, edge_buffer, sizeof(edge_buffer), &hook_ctx);

// Shelf devices only: ask which registry the device was provisioned into.
err = edge_provisioning_get_registration(ctx, &identity, &registration);

edge_device_t device = {
    .serial_number = "<serial-number>",
    .asset_type_id = <asset-type-id>,
    .project_id = <project-id>,
    .region_id = 1,
    .registry_id = <registry-id>,  // or registration.registry_id
};

// Fills the MQTT client ID, username and password (the device JWT).
err = edge_mqtt_credentials_get(ctx, &device, private_key, &credentials);

// Connect your MQTT client, then subscribe to every Fundamentum topic.
for (edge_mqtt_topic_sub_type_t t = 0; t < EDGE_MQTT_TOPIC_SUB_TYPE__COUNT; t++) {
    char topic[128] = {0};
    edge_mqtt_topic_sub_build(t, &device, topic, sizeof(topic));
    mqtt_subscribe(my_mqtt_client, topic, MQTT_QOS_1);
}

err = edge_send_heartbeat(ctx, &device, uptime);
err = edge_send_telemetry(ctx, &device, sub_topic, &telemetry);
err = edge_send_states(ctx, &device, &states);

Connectez votre client MQTT au broker renvoyé par edge_provisioning_get_registration, ou à mqtts.fundamentum-iot.com:8883. Consultez Connect over MQTTS pour connaître les exigences TLS (SNI et CA).

4. Partir d'un exemple

Le dépôt inclut des implémentations complètes des hooks :

Exemple	Plateforme
`examples/Linux`	Linux, avec libcurl (HTTP) et paho-mqtt-c (MQTT)
`examples/FreeRTOS`	FreeRTOS

Et ensuite

Envoyer la télémétrie, les états et les heartbeats pour comprendre ce que la bibliothèque publie.
Actions et encodeurs personnalisés et Mises à jour du micrologiciel (OTA).