Questions fréquentes

IoT magic Builder est une plateforme de gestion IoT qui permet de collecter, visualiser et exploiter les données de vos équipements connectés. Elle comprend plusieurs modules :

• Administration : Gestion des utilisateurs, clients et permissions
• App Builder : Création de tableaux de bord et visualisation des données
• Référentiel : Configuration des types d'équipement et services
• Branding : Personnalisation visuelle de l'interface

La plateforme est organisée selon une hiérarchie stricte :

Les données sont strictement cloisonnées au niveau client :

• Un utilisateur d'un client ne peut jamais voir les données d'un autre client
• Les équipements, sites et variables sont entièrement isolés
• Les tableaux de bord ne peuvent afficher que les données du périmètre autorisé

Certaines configurations peuvent être partagées au sein d'un même CA : types d'équipement, services, groupes d'utilisateurs.

La plateforme supporte 11 langues : Chinois, Allemand, Anglais, Espagnol, Français, Italien, Néerlandais, Polonais, Portugais, Slovène et Turc.

Les traductions s'appliquent à l'interface et aux données (noms de services, variables, équipements). Si une traduction n'existe pas, la langue par défaut s'affiche.

Ces trois mécanismes contrôlent différents aspects de l'accès :

Un utilisateur doit avoir les trois configurés pour interagir avec la plateforme.

Un utilisateur ne peut voir un équipement que s'il est associé à un Groupe d'Accès aux Données (GAD) qui inclut cet équipement. Sans GAD associé, l'utilisateur ne verra aucun équipement, même s'il a accès à l'application App Builder.

Vérifiez dans Administration > Groupes d'Accès aux Données que l'utilisateur est bien associé aux GAD appropriés.

1. Accédez au module Administration > Utilisateurs
2. Cliquez sur Inviter un utilisateur
3. Renseignez les informations (email, nom, prénom)
4. Associez-le à un ou plusieurs Groupes (pour les permissions)
5. Associez-le à un ou plusieurs GAD (pour la visibilité des équipements)
6. Attribuez-lui l'accès aux Applications nécessaires

Le groupe Super administrateur donne des droits complets sur la plateforme :

• Accès à tous les équipements (indépendamment des GAD)
• Peut effectuer toutes les actions
• Peut accéder à tous les modules
• Voit tous les tableaux de bord en mode administration

Oui, un utilisateur peut avoir accès à plusieurs clients au sein d'un même compte d'entreprise. Dans ce cas :

• Il sélectionne le client à la connexion
• Ses droits peuvent différer selon le client
• Les données restent cloisonnées dans chaque contexte

Si l'utilisateur n'a accès qu'à un seul client, il est redirigé automatiquement sans sélection.

1. Créez un Site dans le module Administration
2. Créez un Équipement rattaché à ce site
3. Récupérez les informations de connexion :
   • UUID de l'équipement
   • Clé API du site
   • URL du connecteur
4. Configurez votre équipement pour envoyer des données via HTTPS ou MQTTS

Quand vous créez un équipement basé sur un type, les services définis dans le type sont automatiquement créés sur l'équipement.

Un Item est un composant logique d'un équipement. Il permet de regrouper les variables par fonction ou par sous-système.

Exemple : Un compteur électrique pourrait avoir les items suivants :

• Global : variables générales (statut, version firmware)
• Mesures : variables de mesure (tension, courant, puissance)
• Index : variables d'index (consommation cumulée)

Les items sont définis dans le Référentiel et s'appliquent aux types d'équipement.

Lorsque vous modifiez un type d'équipement dans le Référentiel (ajout de services, modification de formules), vous devez synchroniser les équipements existants :

1. Allez dans Référentiel > Types d'équipement
2. Sélectionnez le type modifié
3. Cliquez sur Synchroniser
4. Les nouveaux services seront créés sur tous les équipements de ce type

Utilisez l'API d'activation : Envoyez une requête avec les informations de l'équipement (numéro de série, clé d'activation). L'équipement est créé automatiquement à la première transmission de données.

Une passerelle est un élément optionnel de la hiérarchie qui sert de hub principal pour connecter plusieurs équipements.

Les passerelles sont utiles lorsque plusieurs équipements communiquent via un concentrateur commun avant d'envoyer les données à la plateforme.

Les variables calculées permettent de créer des indicateurs dérivés sans modifier la configuration de vos équipements.

Le MappingConfig DataHub est l'identifiant technique d'une variable au format : itemType|itemIndex|serviceId

Exemple : Mesures|0|temperature

Il est essentiel pour cibler la bonne variable lors de l'envoi de données à la plateforme. Vous le trouvez dans les détails de la variable après sa création.

Trois méthodes sont disponibles :

1. Via les services (recommandé) : Définissez un service dans le Référentiel, associez-le à un type d'équipement. Les variables seront créées automatiquement sur tous les équipements de ce type.

2. Via l'API : Les variables sont créées automatiquement lors de la première transmission de données.

3. Via import de dictionnaire : Importez un fichier définissant toutes les variables.

Les formules calculées supportent :

Opérateurs arithmétiques : +, -, *, / et les parenthèses ( )

Opérateurs de comparaison : >, <, <=, >=, =

Opérateurs logiques : || (ou), && (et), ! (inverse)

Pour utiliser une variable dans la formule, écrivez son nom entre crochets : [NomVariable]

La plateforme propose quatre types de formules :

Lorsque vous modifiez la formule d'une variable calculée, la plateforme recalcule automatiquement l'historique des données avec la nouvelle formule.

Un Service est un modèle de variable réutilisable. Il permet de :

• Créer rapidement des variables identiques sur plusieurs équipements
• Garantir la cohérence des données entre équipements similaires
• Centraliser les définitions et les formules calculées

Un service peut être simple (variable classique) ou calculé (avec une formule).

Deux protocoles sont supportés :

Les données doivent être envoyées au format JSON avec les champs obligatoires : device, at, protocol et data.

Format Stream :

{
  "protocol": "v3",
  "device": "UUID-de-l-equipement",
  "at": 1554884039,
  "checksum": "sha1-hash",
  "data": {
    "ver": "S1",
    "dataset": [
      { "at": 1554884039, "ref": "temperature", "value": 21.5 }
    ]
  }
}

Le champ checksum est obligatoire en v3, optionnel en v2.

Le checksum v3 est calculé en concaténant les champs at et data (sans espaces), puis en appliquant un hash SHA1 avec le mot de passe de l'équipement comme clé.

La limite est de 1000 points de données par requête. Au-delà, la requête sera rejetée.

Si vous avez plus de données à envoyer, divisez-les en plusieurs requêtes.

Recommandations :

1. Stockez localement les données en cas d'échec (prévoir une capacité de stockage adaptée)
2. Réessayez avec des délais croissants : 10 minutes, puis 1 heure, puis toutes les 24 heures
3. Dès qu'un envoi réussit, renvoyez toutes les données stockées en respectant la limite de 1000 points par requête

• Clé API : Disponible au niveau du Site dans Administration > Sites > Détails du site
• UUID : Disponible dans les détails de l'Équipement dans Administration > Équipements

Ces informations sont nécessaires pour authentifier et cibler vos envois de données.

1. Accédez au module App Builder
2. Cliquez sur Créer un tableau de bord
3. Configurez les paramètres globaux :
   • Périmètre (localisation, périodes)
   • Grille (colonnes, lignes)
   • Arrière-plan
4. Ajoutez des widgets depuis la librairie
5. Configurez chaque widget (données, période, apparence)

Un slider est idéal pour l'affichage sur TV/totem où plusieurs vues doivent défiler automatiquement.

Quand un widget est configuré avec "Depuis la relation", il récupère ses données en fonction :

• De la localisation sélectionnée dans le panneau de navigation du dashboard
• De la période définie dans le sélecteur temporel

Cela permet de créer des widgets dynamiques qui s'adaptent au contexte de navigation de l'utilisateur.

1. Sélectionnez un widget de type Graphique multi-séries
2. Dans la configuration, mode "Depuis la variable"
3. Ajoutez plusieurs variables en les sélectionnant une par une
4. Configurez les options d'affichage (couleurs, axes, légendes)

La plateforme propose deux widgets dédiés aux alarmes :

Les seuils d'alerte peuvent être définis sur les services dans le Référentiel. Les formules conditionnelles permettent également de créer des alarmes personnalisées.

Plusieurs widgets permettent l'export de données :

Pour exporter, cliquez sur l'icône de téléchargement disponible dans l'en-tête du widget (si l'option est activée dans la configuration).

1. Ouvrez le tableau de bord en mode édition
2. Accédez aux Paramètres > Gestion des accès
3. Choisissez le mode de visibilité :
   • Tous : Visible par tous les utilisateurs
   • Tous sauf... : Visible par tous sauf les groupes/GAD sélectionnés
   • Seulement... : Visible uniquement par les groupes/GAD sélectionnés

1. Ouvrez le tableau de bord
2. Accédez aux Paramètres > Liens publics
3. Activez les liens publics
4. Cliquez sur Créer un lien
5. Configurez l'utilisateur technique associé
6. Copiez l'URL générée

L'URL permet d'accéder au dashboard sans connexion, en lecture seule.

Utilisez un lien public :

1. Créez un lien public pour votre tableau de bord
2. Ouvrez l'URL sur la TV/totem
3. Le dashboard s'affiche en lecture seule
4. Pour un défilement automatique, utilisez un Slider
5. Utilisez le mode plein écran (F11 ou bouton dédié)

Lorsque vous régénérez une URL publique :

• L'ancienne URL devient immédiatement invalide
• Les sessions actives utilisant l'ancienne URL seront déconnectées
• Seule la nouvelle URL permettra d'accéder au dashboard

Le mode plein écran est idéal pour l'affichage sur TV ou totem de supervision.

Pour activer le mode plein écran :

• Appuyez sur la touche F11 de votre navigateur
• Ou cliquez sur le bouton plein écran en bas à droite du tableau de bord

Comportement en lien public :

• Le header de l'application est automatiquement masqué
• Si le lien pointe vers une seule page, le menu latéral est également masqué
• La langue affichée correspond à celle de l'utilisateur technique associé au lien

1. Créez une page au format A4 (configuration de grille spécifique)
2. Dans Référentiel > Rapports, créez une configuration de rapport
3. Associez la page A4 au rapport
4. Configurez un planificateur (fréquence, période d'analyse)
5. Générez manuellement ou laissez le planificateur générer automatiquement

1. Accédez à la configuration du rapport
2. Créez un planificateur
3. Définissez :
   • La fréquence (quotidien, hebdomadaire, mensuel)
   • La période d'analyse (relative ou absolue)
   • Les destinataires (email, FTP)
4. Activez le planificateur

Les rapports seront générés et envoyés automatiquement selon la configuration.

Le rendu PDF dépend de la configuration A4 de la page :

• Vérifiez que la grille est bien configurée pour le format A4
• Les widgets doivent être dimensionnés pour tenir sur une page A4
• Utilisez la prévisualisation avant de générer le rapport final

1. Créez une Application dans Mon profil > Mes applications
2. Obtenez un token d'accès via OAuth 2.0
3. Utilisez le token dans l'en-tête Authorization: Bearer {token}
4. Consultez la documentation Swagger pour les endpoints disponibles

URL de base : https://api.magicbuilder.io/

Par défaut, un token d'accès est valide 300 secondes (5 minutes).

Lorsque le token expire, vous devez en obtenir un nouveau en répétant la procédure d'authentification.

Choisissez le mode minimal nécessaire pour votre intégration (principe du moindre privilège).

Vérifiez les points suivants :

1. L'équipement est-il actif ? Vérifiez son statut dans Administration
2. La variable existe-t-elle ? Vérifiez qu'elle est bien créée sur l'équipement
3. Le MappingConfig est-il correct ? Format : itemType|itemIndex|serviceId
4. La période est-elle correcte ? Vérifiez que la période du widget couvre les dates d'envoi
5. Avez-vous accès à l'équipement ? Vérifiez votre GAD

Les équipements visibles dépendent de votre Groupe d'Accès aux Données (GAD).

Contactez votre administrateur pour vérifier que vous êtes bien associé au GAD contenant ces équipements.

Vérifiez les points suivants :

1. Clé API : Vérifiez qu'elle est correcte et correspond au site
2. UUID : Vérifiez l'identifiant de l'équipement dans Administration
3. Format JSON : Validez la structure de votre payload
4. MappingConfig : Vérifiez que le format est correct (itemType|itemIndex|serviceId)
5. Limite : Respectez la limite de 1000 points de données par requête

Causes possibles :

1. Aucune donnée n'existe pour la période sélectionnée
2. La variable n'est pas correctement configurée sur le widget
3. La localisation du dashboard ne correspond pas aux équipements disponibles
4. Vous n'avez pas les droits d'accès (GAD) sur les équipements concernés