Expert - Interface passerelle télécom

Cette interface sert à communiquer facilement avec le HS/FS au moyen de sa propre interface. Le HS/FS envoie un télégramme à chaque modification d'un objet de communication. Pour ce faire, les objets de communication sont caractérisés individuellement ou globalement.

Cette interface est disponible dans la variante 1 (mode de compatibilité) depuis la version v2.2 du micrologiciel HS/FS.

La variante 2 existe depuis la version v4.7 du micrologiciel HS/FS : communication cryptée via des WebSockets (https).

1.Protocole de communication

1.1.Type d'accès

Pour pouvoir communiquer avec le HS/FS via l'interface passerelle télécom, il est nécessaire d'activer au moins l'une des deux méthodes d'accès dans Expert (accessibles via Réglages de projet -> Réseau -> Passerelle télécom).

Activer WebSocket
Activer mode de compatibilité

Ces deux méthodes utilisent un moniteur HS qui assure la liaison avec l'interface passerelle télécom.

1.1.1.Activer WebSocket

Cette méthode permet 10 accès simultanés au HS/FS.

La version du moniteur HS qui utilise cette méthode fait partie intégrante du logiciel Expert, l'activer à la rubrique Données de base -> Réglages de projet -> Interface :

soit

l'option Tous doit être activée

soit

l'option Défini par l'utilisateur doit être activée
et
la case à cocher hsmonitor doit être activée.

Le moniteur HS est alors également transféré sur le HS/FS et peut être appelé via un navigateur via l'URL suivant :

HTTPS://HS_IP/opt/hsmonitor/index.html

IP-ADR est l'adresse IP du HS/FS, complétée, le cas échéant, par un des ports HTTPS activés dans l'Expert HS/FS, sous « Réglages de projet -> Réseau -> Sécurité ».

1.1.2.Mode de compatibilité

Cette méthode est disponible à partir de la version v2.2 du micrologiciel et permet d'établir une liaison non cryptée avec le HS/FS.
Cette méthode permet 10 accès simultanés au HS/FS.

La version du moniteur HS fonctionnant avec cette méthode est un programme exécutable sur un PC Windows (hsmonitor.exe n'est plus disponible à partir de la v4.7).
Cette méthode peut être utilisée parallèlement à l'accès via WebSockets.

2.Informations destinées aux développeurs

2.1.Authentification

Il est indispensable d'entrer un URL pour élaborer la liaison WebSocket de logiciels propres au HS/FS. L'URL à utiliser contient l'authentification requise et doit être structuré comme suit :

wss://HS_IP/cogw?authorization=AUTH

IP-ADR est l'adresse IP du HS/FS, complétée, le cas échéant, par un des ports HTTPS activés dans l'Expert HS/FS, sous « Réglages de projet -> Réseau -> Sécurité ».

AUTH est la clé appropriée indiquée dans l'Expert, dans « Réglages de projet -> Réseau -> Passerelle télécom » . Elle doit être saisie codée en base64.

En cas d'échec de l'authentification, la liaison n'est pas établie et le HS/FS répond par le code d'état 403 (Forbidden). Si l'interrogation est incomplète, le HS/FS répond par le code d'état 400 (Bad Request).

Attention

L'échec de l'authentification bloque l'adresse IP du client pendant 5 secondes. Pendant cette période, l'appareil renvoie le code d'état 503 à chaque interrogation.

2.2.Comportement au démarrage

Lorsque l'appareil démarre, le serveur HTTP est déjà disponible avant que l'installation soit terminée. Pendant cette période, l'appareil renvoie le code d'état 503 à chaque interrogation. La réponse contient en outre l'en-tête HTTP « Retry-After ». Ce champ peut être analysé pour lancer automatiquement une nouvelle tentative lorsque la durée exprimée en secondes est écoulée.

2.3.Communication

La communication avec le HS/FS se fait au moyen de données sous la forme de structures JSON.

2.3.1.Conversion des adresses de groupes

L'adresse de groupe est indiquée dans l'Expert HS/FS sous forme x/y/z ou x/z. Dans les télégrammes envoyés au HS/FS et ceux venant du HS/FS, l'adresse de groupe est indiquée au format numérique. Exécuter la conversion comme suit :

Expert -> numérique
x/y/z est convertit en : GRPADR = x*2048 + y*256 + z
x/z est converti en : GRPADR = x*2048 + z

Numérique -> Expert
x = GRPADR / 2048, les décimales sont ignorées
y = (GRPADR - x*2048) / 256, les décimales sont ignorées
z = (GRPADR - x*2048 - y*256)

Dans sa forme numérique, l'adresse de groupe de l'attribut « ganum » est indiquée dans le fichier XML.

2.3.2.Télégramme au HS/FS

Structure :
{"cmd": COMMAND, "ga": GRPADR, "value": VAL]} (avec cmd = 1,2)

ou

{"cmd": COMMAND, "ga": GRPADR} (avec cmd = 3,4,5,6)

COMMAND est un nombre entier de 1 à 6. Des explications se trouvent dans le tableau ci-dessous.

GRPADR est l'adresse de groupe. Elle doit être indiquée sous forme numérique et peut être calculée à partir des formats utilisés dans Expert.

La mention du 3e paramètre « value » est optionnelle et dépend du 1er Voir le tableau ci-dessous.

`COMMAND`	Description	`VAL`
1	Définit la valeur absolue	Décimale ou texte en fonction de l'objet de communication respectif. Un texte doit être saisi codé en base64.
2	Définit la valeur relative	Décimale
3	Step+	non indiquée
4	Step-	non indiquée
5	Liste+	non indiquée
6	Liste-	non indiquée

2.3.3.Télégramme venant de HS/FS

Le HS/FS est en mesure d'envoyer 3 types différents de télégrammes :

Initialisation
Initialisation terminée
Télégramme consécutif

2.3.3.1.Initialisation

Ce télégramme est envoyé après un redémarrage, pour chacun des objets de communication communiqués via la passerelle télécom.

Structure :
{"cmd": 2, "ga": GRPADR, "value": VAL]}

GRPADR est l'adresse de groupe. Elle doit être indiquée sous forme numérique et peut être calculée à partir des formats utilisés dans Expert.

VAL peut être un nombre entier ou une chaîne. S'il s'agit d'une chaîne, elle est codée en base64.

2.3.3.2.Initialisation terminée

Ce télégramme est envoyé par le HS/FS lorsque, après un redémarrage, l'initialisation de tous les objets de communication communiqués via la passerelle télécom est terminée.

Structure :
{"cmd": 2}

2.3.3.3.Télégramme consécutif

Ce télégramme est envoyé lorsqu'une valeur a été attribuée à l'objet de communication indiqué. Il est également envoyé si la valeur existant jusque-là concorde avec la nouvelle valeur de l'objet de communication.

Structure :
{"cmd": 1, "ga": GRPADR, "value": VAL]}

GRPADR est l'adresse de groupe. Elle doit être indiquée sous forme numérique et peut être calculée à partir des formats utilisés dans Expert.

VAL peut être un nombre entier ou une chaîne. S'il s'agit d'une chaîne, elle est codée en base64.

2.4.Noms en texte clair des objets de communication

Les noms des objets de communication peuvent être appelés sous forme de fichier XML via l'URL suivant.

HTTPS://HS_IP/opt/sys/cobjects.xml

IP-ADR est l'adresse IP du HS/FS, complétée, le cas échéant, par un des ports HTTPS activés dans l'Expert HS/FS, sous « Réglages de projet -> Réseau -> Sécurité ».

Exemple : HTTPS://192.168.0.11:443/opt/sys/cobjects.xml
Structure de données du fichier XML (exemple) :

 <cobject
    id="911"
    used="0"
    type="eib"
    path="01 Lighting\2nd Floor\"
    fmt="EIS1+EIS2+EIS7_1BIT"
    fmtex="integer"
    name="FL02 Light"
    rem="0"
    init="0"
    min="0"
    max="1"
    step="0"
    list=""
    ga="1/2/1"
    ganum="2561"
    cogws="1"
    cogwr="0"
    scan="1"
    sbc="1"
    read="0"
    transmit="1"
 />

Tous les champs sont traités dans Expert HS/FS, dans le point de programme Objets de communication. Vous trouverez des informations complémentaires au sujet des champs dans l'aide en ligne de l'Expert HS/FS concernant les objets de communication.

Attribut	Description
id	Numéro univoque de l'objet de communication
used	1 = l'objet de communication est utilisé dans le projet. 0 = sans utilisation.
type	Type d'objet de communication « internal » = objet de communication interne « eib » = objet de communication EIB
path	Dossier dans lequel l'objet de communication est déposé dans Expert HS/FS.
fmt	Format de données 1 Texte en clair (les textes se trouvent dans le fichier minmax.txt, dans le sous-répertoire Expert « /dat ») `EIS1+EIS2+EIS7_1BIT EIS6_8BIT NONEIS_8BIT_RTR EIS5_16BIT EIS2+EIS6_8BIT EIS?_8BIT EIS10_16BIT_UNSIGNED EIS10_16BIT_SIGNED EIS11_32BIT_UNSIGNED EIS11_32BIT_SIGNED EIS?_14BYTE EIS3_3BYTE_TIME EIS4_3BYTE_DATE EIS?_4BIT EIS9_4BYTE EIS8_2BIT EIS?_DALI EIS?_SRO EIS?_3BYTE`
fmtex	Format de données 2 `integer number text date time unknown`
name	Nom de l'objet de communication
rem	1 = permanent dans HS/FS 0 = non permanent
init	Valeur initiale
min	Valeur minimum
max	Valeur maximum
step	Taille de pas
list	Liste
ga	Adresse de groupe telle qu'elle est saisie dans Expert HS/FS
ganum	Adresse de groupe (numérique)
cogws	Envoyer via la passerelle télécom
cogwr	Recevoir via la passerelle télécom
scan	1 = interroger au démarrage 0 = ne pas interroger au démarrage
sbc	1 = Send by Change 0 = pas de Send by Change
read	1 = lisible 0 = non lisible
transmit	1 = transmettre 0 = ne pas transmettre