Regulation de centrale

Alemca permet d'envoyer des commandes de régulation à une ou plusieurs centrales. Ces commandes peuvent être envoyées de manière individuelle ou groupée, en utilisant soit une liste d'équipements, soit un tag.

Une entitée Alemca comporte des attributs, nous les utilisons ici pour configurer la commande de régulation.

La configuration coté équipement (installation du script + configuration modbus) Alemca se fait via le support Alemca

Configuration de la centrale

Pour configurer une centrale, vous devez d'abord vous assurer qu'elle est correctement ajoutée à votre système Alemca (voir guide d'installation). Une fois la centrale créé, vous pouvez accéder à ses attributs pour configurer la commande.

Attributs

ExplicationsInterface WebAPI Alemca

Les attributs sont des champs de configuration qui permettent de définir comment Alemca interagit avec la centrale. Pour la régulation, nous avons besoin de configurer un attribut spécifique nommé CMD_REGULATION. Les informations a remplir sont généralement connues par l'automaticien ou l'intégrateur qui a installé la centrale.

Cet attribut doit contenir les informations nécessaires pour envoyer des commandes de démarrage et d'arrêt à la centrale via le protocole de communication Modbus.

Il faut dans un premier temps se diriger vers la page d'attribut de l'équipement.

Rendez-vous sur https://app.alemca.io/

Cliquez sur l'équipement de la centrale que vous souhaitez configurer, puis cliquez sur l'onglet "Attributs":

Cliquez le mode Edition:

Ajouter un nouveau champ ou éditez un champ existant nommé CMD_REGULATION avec les informations suivantes:

{
    "address_off": "324",
    "address_on": "324",
    "byte_order_off": "AB",
    "byte_order_on": "AB",
    "data_type_off": "int16",
    "data_type_on": "int16",
    "length_off": "1",
    "length_on": "1",
    "modbus_connectors": ["modbus1"],
    "slave_id_off": "1",
    "slave_id_on": "1",
    "value_off": "0",
    "value_on": "1"
}

Explication des champs:

• address_off: Adresse Modbus pour la commande d'arrêt.

• address_on: Adresse Modbus pour la commande de démarrage.

• byte_order_off: Ordre des octets pour la commande d'arrêt.

• byte_order_on: Ordre des octets pour la commande de démarrage.

• data_type_off: Type de données pour la commande d'arrêt.

• data_type_on: Type de données pour la commande de démarrage.

• length_off: Longueur des données pour la commande d'arrêt.

• length_on: Longueur des données pour la commande de démarrage.

• modbus_connectors: Connecteurs Modbus utilisés.

• slave_id_off: ID de l'esclave pour la commande d'arrêt.

• slave_id_on: ID de l'esclave pour la commande de démarrage.

• value_off: Valeur pour la commande d'arrêt.

• value_on: Valeur pour la commande de démarrage.

Vous pouvez également configurer l'attribut CMD_REGULATION via l'API REST d’Alemca.

Lire tous les attributs

Méthode: GET
URL: https://api.alemca.io/v2/core/entities/<entity_ident>/attributes
Headers:

api-key: <your-api-key>

Lire un attribut spécifique

Méthode: GET
URL: https://api.alemca.io/v2/core/entities/<entity_ident>/attributes/CMD_REGULATION
Headers:

api-key: <your-api-key>

Créer ou modifier un attribut

Méthode: POST
URL: https://api.alemca.io/v2/core/entities/<entity_ident>/attributes/CMD_REGULATION
Headers:

Content-Type: application/json
api-key: <your-api-key>

Body:

{
"value": {
    "address_off": "324",
    "address_on": "324",
    "byte_order_off": "AB",
    "byte_order_on": "AB",
    "data_type_off": "int16",
    "data_type_on": "int16",
    "length_off": "1",
    "length_on": "1",
    "modbus_connectors": ["modbus1"],
    "slave_id_off": "1",
    "slave_id_on": "1",
    "value_off": "0",
    "value_on": "1"
}
}

Explication des champs:

• address_off: Adresse Modbus pour la commande d'arrêt.

• address_on: Adresse Modbus pour la commande de démarrage.

• byte_order_off: Ordre des octets pour la commande d'arrêt.

• byte_order_on: Ordre des octets pour la commande de démarrage.

• data_type_off: Type de données pour la commande d'arrêt.

• data_type_on: Type de données pour la commande de démarrage.

• length_off: Longueur des données pour la commande d'arrêt.

• length_on: Longueur des données pour la commande de démarrage.

• modbus_connectors: Connecteurs Modbus utilisés.

• slave_id_off: ID de l'esclave pour la commande d'arrêt.

• slave_id_on: ID de l'esclave pour la commande de démarrage.

• value_off: Valeur pour la commande d'arrêt.

• value_on: Valeur pour la commande de démarrage.

Usage

Création

ExplicationsInterface WebAPI Alemca

Une fois la centrale configurée, vous pouvez créer une commande de régulation. Cette commande peut être envoyée à une seule centrale ou à plusieurs centrales en utilisant un tag ou une liste d'équipements.

Choisissez la méthode qui vous convient le mieux pour envoyer la commande de régulation.

Une seule centralePlusieurs centrales

Pour envoyer une commande de régulation sur une seule centrale vous pouvez le faire sur la page de l'équipement depuis l'onglet "Commandes":

Cliquer sur "Créer un nouveau Job" puis "regulation_centrale":

Remplissez les champs nécessaires:

Planifier: Valeur "On" ou "Off", permet d'activer la configuration du début de la commande de régulation.

Horaire: Permet de planifier la commande de régulation à une date et heure précise.

Fin: Permet de planifier la fin de la commande de régulation à une date et heure précise.

Commentaire: Optionnel, permet d'ajouter un commentaire à la commande de régulation.

Notification Email: Permet d'envoyer une notification par email à l'adresse configurée lors de la création de la commande.

Notification Status: Entrez un status (example "error"), cela enverra un email lorsque se status apparait.

Pour envoyer une commande de régulation sur plusieurs centrales, vous pouvez le faire depuis l'onglet "commandes".

Rendez-vous sur la page des commandes, puis cliquez sur "Créer un nouveau Job" et sélectionnez "regulation_centrale":

Sélectionnez le tag ou la liste d'équipements que vous souhaitez utiliser pour envoyer la commande de régulation:

Remplissez les champs nécessaires:

Horaire: Permet de planifier la commande de régulation à une date et heure précise.

Fin: Permet de planifier la fin de la commande de régulation à une date et heure précise.

Commentaire: Optionnel, permet d'ajouter un commentaire à la commande de régulation.

Notification Email: Permet d'envoyer une notification par email à l'adresse configurée lors de la création de la commande.

Notification Status: Entrez un status (example "error"), cela enverra un email lorsque se status apparait.

Une seule centralePlusieurs centralesLire une commandeLire un groupe de commandes

Méthode: POST
URL: https://api.alemca.io/v3/commands/tasks/6cdc1f68-5f44-4ec7-91ad-952d58df6023/jobs
Headers:

Content-Type: application/json
api-key: <your-api-key>

Body:

{
"entity_ident": "<entity_ident>",
"variables": {
    "end_timestamp": 1753183624
}
}

Pour planifier une régulation à une certaine date, il faut ajouter dans le body le champ "scheduled_time". La commande ne sera exécutée qu'à partir de cette date.

Body:

{
"entity_ident": "<entity_ident>",
"variables": {
    "end_timestamp": 1754183624
},
"scheduled_time" : 1753883624
}

Variables :

• variables.end_timestamp : timestamp UNIX en secondes indiquant la fin prévue de la commande. Il détermine quand la régulation doit s'arrêter automatiquement.
• scheduled_time : Timestamp UNIX en secondes indiquant la date d'exécution de la commande.

Méthode: POST
URL: https://api.alemca.io/v3/commands/tasks/6cdc1f68-5f44-4ec7-91ad-952d58df6023/jobs/list
Headers:

Content-Type: application/json
api-key: <your-api-key>

Body:

{
"group_name": "nom_du_groupe",
"ident_list": [
    "<entity_id_1>",
    "<entity_id_2>"
],
"variables": {
    "end_timestamp": 1753183624
}
}

Pour planifier une régulation à une certaine date, il faut ajouter dans le body le champ "scheduled_time". La commande ne sera exécutée qu'à partir de cette date.

Body:

{
"entity_ident": "<entity_ident>",
"variables": {
    "end_timestamp": 1754183624
},
"scheduled_time" : 1753883624
}

Paramètres :

• group_name : Chaîne identifiant le groupe de commandes. Cela permet de retrouver toutes les commandes envoyées ensemble.

• ident_list : Liste des identifiants d’équipements à cibler.

• variables.end_timestamp : Timestamp UNIX en secondes indiquant la fin de la commande.

• scheduled_time : Timestamp UNIX en secondes indiquant la date d'exécution de la commande.

Méthode: GET
URL: https://api.alemca.io/v3/commands/jobs/<job_ident>
Headers:

api-key: <your-api-key>

Permet de lire les détails d'une commande de régulation spécifique à partir de son identifiant.

Méthode: GET
URL: https://api.alemca.io/v3/commands/jobs?group_ident=<group_ident>
Headers:

api-key: <your-api-key>

Le group_ident est retourné dans la réponse lors de la création d’une commande multiple. Cette requête permet d’obtenir toutes les commandes liées à ce groupe.

"Annulation de commande"

Interface WebAPI Alemca

WIP: Ajouter la procédure d’annulation de commande via l’interface web.

Méthode: PATCH
URL: https://api.alemca.io/v3/commands/jobs/<job_ident>/cancel
Headers:

api-key: <your-api-key>

Permet d'annuler une commande de régulation en cours ou à venir. Une fois annulée, la commande ne sera plus exécutée.
Le job_ident est l'identifiant unique de la commande que vous souhaitez annuler. Cette opération est irréversible.