Module smartCORE ModBus
Description
Le module « modbus » lit principalement les registres ModBus des participants ModBus. Ces participants peuvent être connectés
- via une liaison série (ModBus/RTU)
- via TCP (ModBus/TCP)
Interfaces et protocoles utilisés
- ModBus
Configuration JSON
La section suivante décrit l'ensemble de la configuration JSON du module et explique chacun des paramètres.
Exemple de configuration
Voici un exemple de configuration ModBus/TCP :
{
"module": "ModBus",
"comment": "ModBus/TCP config",
"factory": "modbus",
"config": {
"version": 1,
"type": "modbus",
"enable": true,
"pollCycleInMilliseconds": 1000,
"transport": {
"type": "tcp",
"ipAddress": "192.168.0.1",
"ipPortNumber": 502,
"timeoutInMilliseconds": 200
},
"devices": [
{
"enable": true,
"deviceName": "Device Name",
"deviceAddress": 1,
"readChannels": [
{
"name": "Channel Name",
"address": 49152,
"registerType": "HoldingReg",
"registerFormat": "REAL",
"byteOrder": "ABCD",
"bitOffset": 0,
"unit": "",
"scale": 1.0,
"offset": 0.0
}
]
}
]
}
}
Paramètres globaux du module
| Nom du paramètre | Requis | Type de données | Plage de valeurs pertinente | Défaut | Description |
|---|---|---|---|---|---|
| version | OUI | INT | 1 | Version du protocole ModBus | |
| type | OUI | STRING | "modbus" | Interface série pour la communication | |
| enable | OUI | BOOL | true | Commutateur pour la production des données dans des smartCHANNELs | |
| pollCycleInMilliseconds | OUI | INT | 1 - | Intervalle d'interrogation [ms] des accès ModBus | |
| transport | OUI | Objet JSON | Configuration de la couche de transport ModBus (voir ci-dessous) | ||
| devices | OUI | Tableau JSON d'objets JSON | Liste des participants ModBus | ||
| pollCycleInNanoseconds | Non | INT | 1 - | 100000000 | Intervalle d'interrogation [ns]. Si la clé est définie, elle a priorité sur pollCycleInMilliseconds. Si les deux sont absentes, 100 ms sont utilisées |
| enableInternalDataReduction | Non | BOOL | true, false | false | Associe à chaque canal créé une réduction de données (absTolerance 0.0, timeoutMs 60000) : les valeurs inchangées ne sont pas écrites, mais le sont de nouveau au plus tard après 60 s |
| autoGroup | Non | BOOL | true, false | true | Regroupe automatiquement les registres voisins d'un appareil en blocs de registres lus en une seule transaction (voir Blocs de registres) |
| autoGroupAllowGaps | Non | BOOL | true, false | false | Autorise des lacunes à l'intérieur d'un bloc : les registres non nécessaires sont lus en même temps au lieu de scinder le bloc |
| maxRegisterGroup | Non | INT | 1 - 125 | 125 | Nombre maximal de registres d'un bloc. Les valeurs supérieures sont limitées à 125 avec un avertissement — ModBus n'en autorise pas davantage en une transaction |
| useF23withoutOutputs | Non | BOOL | true, false | false | Utilise le code de fonction 23 (Read/Write Multiple Registers) même lorsqu'il n'y a rien à écrire (à partir de smartCORE 2.12) |
| minimalChannelAlarmCount | Non | INT | 1 - | 2 | Nombre d'échecs immédiatement consécutifs après lequel un bloc de registres est désactivé (voir Timeout et désactivation) |
| retryAfterBlockFailS | Non | INT | 0 - | 0 | Temps d'attente [s] après lequel un bloc de registres désactivé est de nouveau tenté. 0 = pas de nouvelle tentative, le bloc reste hors service pour la mesure (à partir de smartCORE 2.12) |
| workloadAsChannel | Non | BOOL | true, false | false | Crée un canal de diagnostic qui indique la charge du bus |
| workloadChannelBuffersize | Non | INT | 1 - | 100 | Taille du tampon du canal de charge du bus, en éléments |
| workloadChannel | Non | STRING ou objet JSON | Nom ou définition complète du canal de charge du bus |
Paramètres de transport spécifiques à ModBus/TCP ("transport")
| Nom du paramètre | Requis | Type de données | Plage de valeurs pertinente | Défaut | Description |
|---|---|---|---|---|---|
| type | OUI | STRING | "tcp" | Sélection de ModBus/TCP | |
| ipAddress | OUI | STRING | Adresse IP valide | Adresse IP de l'appareil ModBus | |
| ipPortNumber | OUI | INT | Numéro de port IP valide | Numéro de port IP de l'appareil ModBus (à régler sur 502, sauf indication contraire) | |
| timeoutInMilliseconds | OUI | INT | 1 - | Timeout [ms] de la connexion TCP (à régler sur 200, sauf indication contraire) |
Paramètres de transport spécifiques à ModBus/RTU ("transport")
| Nom du paramètre | Requis | Type de données | Plage de valeurs pertinente | Défaut | Description |
|---|---|---|---|---|---|
| type | OUI | STRING | "rtu" | Sélection de ModBus/RTU | |
| baudRate | OUI | INT | Débit en bauds ModBus valide | Débit en bauds de l'interface série | |
| dataBits | OUI | INT | 5 - 8 | Bits de données de l'interface série | |
| parity | OUI | STRING | "no", "even", "odd" | Parité de l'interface série | |
| stopBits | OUI | DOUBLE | 1.0, 1.5, 2.0 | Bits d'arrêt de l'interface série | |
| portName | OUI | STRING | Fichier de périphérique valide | Fichier de périphérique de l'interface série | |
| timeoutInMilliseconds | OUI | INT | 1 - | Timeout de réponse [ms] de la liaison série. Il limite la durée d'attente de la réponse d'un participant et est transmis à libmodbus sous la forme modbus_set_response_timeout() | |
| deviceTimeoutInMilliseconds | Non | INT | 0 - | 0 | Timeout supplémentaire [ms] entre les interrogations de participants ModBus différents |
| readDelayMs | Non | INT | 0 - | Remplace le silence de trame t3.5 [ms] respecté avant chaque requête. Sans cette clé, il est calculé à partir du débit en bauds (voir Silence de trame) |
Paramètres d'appareil ModBus ("devices")
| Nom du paramètre | Requis | Type de données | Plage de valeurs pertinente | Défaut | Description |
|---|---|---|---|---|---|
| enable | OUI | BOOL | true | Commutateur d'activation de l'appareil ModBus | |
| deviceName | OUI | STRING | Nom de l'appareil ModBus | ||
| deviceAddress | OUI | INT | 1 - | Adresse de l'appareil ModBus | |
| readChannels | OUI | Tableau JSON d'objets JSON | voir ci-dessous |
Les clés autoGroup, autoGroupAllowGaps, maxRegisterGroup et useF23withoutOutputs
peuvent en outre être indiquées par appareil et y remplacent alors la valeur globale.
Configuration des canaux ModBus ("readChannels")
| Nom du paramètre | Requis | Type de données | Plage de valeurs pertinente | Défaut | Description |
|---|---|---|---|---|---|
| name | OUI | STRING | Nom du smartCHANNEL | ||
| address | OUI | INT | Adresse du registre ModBus | ||
| registerType | OUI | STRING | Type de registre ModBus valide | Type du registre ModBus ("InputReg", "HoldingReg", "Coil", "Status", "0x17" (lecture seule)) | |
| registerFormat | OUI | STRING | Format de registre ModBus valide | Format du registre ModBus ("I8","I16","I32","I64","UI8","UI16","UI32","UI64","REAL","BOOL") | |
| byteOrder | OUI | STRING | voir ci-dessous | Ordre des octets de la valeur, voir Ordre des octets | |
| bitOffset | OUI | UINT | Décalage en bits de la valeur à interpréter | ||
| unit | OUI | STRING | Unité du smartCHANNEL | ||
| scale | OUI | DOUBLE | Mise à l'échelle du smartCHANNEL | ||
| offset | OUI | DOUBLE | Offset du smartCHANNEL | ||
| enable | Non | BOOL | true, false | true | Un canal avec false n'est ni créé ni lu |
| pollingIntervalMultiplicator | Non | INT | 1 - | 1 | Le bloc de registres de ce canal n'est lu qu'à chaque n-ième cycle d'interrogation |
| registerGroup | Non | INT | 0 - | Affecte manuellement le canal à un bloc de registres. Les canaux ayant le même numéro forment un bloc et sont exclus du regroupement automatique |
Configuration des canaux ModBus ("readChannelGroups")
Il est également possible de regrouper plusieurs configurations de canaux dans un tableau JSON, de sorte que les registres ModBus sous-jacents à ce groupe puissent être lus en une seule étape (si le type de registre est identique). Ce tableau readChannelGroup ainsi regroupé peut ensuite être listé dans le tableau JSON « readChannelGroups », par exemple
"readChannelGroups": [
[
{
"name": "Channel 1",
"address": 49152,
"registerType": "HoldingReg",
"registerFormat": "REAL",
"byteOrder": "ABCD",
"bitOffset": 0,
"unit": "",
"scale": 1.0,
"offset": 0.0
},
{
"name": "Channel 2",
"address": 49158,
"registerType": "HoldingReg",
"registerFormat": "REAL",
"byteOrder": "ABCD",
"bitOffset": 0,
"unit": "",
"scale": 1.0,
"offset": 0.0
}
]
]
On peut spécifier soit « readChannels », soit « readChannelGroups ».
Blocs de registres
Les canaux d'un appareil ne sont pas lus individuellement. smartCORE les regroupe en blocs de registres : un bloc est une plage d'adresses contiguë d'un type de registre et est lu en exactement une transaction ModBus. Chaque canal est alimenté par exactement un bloc.
Le regroupement se fait selon le type de registre et l'adresse. Les quatre espaces d'adressage ModBus (Coil, Discrete Input, Input Register, Holding Register) sont indépendants les uns des autres — Coil 4 et Input Register 4 sont des choses différentes et ne se retrouvent jamais dans le même bloc. Un nouveau bloc commence dès que
- la plage comprendrait plus de
maxRegisterGroupregistres, ou - le registre suivant ne suit pas immédiatement le précédent et
autoGroupAllowGapsvautfalse.
Avec autoGroupAllowGaps: true, les lacunes sont comblées : le bloc lit aussi des registres dont aucun
canal n'a besoin, mais économise en contrepartie une transaction. Cela vaut la peine pour de petites
lacunes et des accès coûteux, pas pour des adresses très éloignées les unes des autres.
Pour déterminer soi-même la répartition, on attribue registerGroup à chaque canal : les canaux ayant
le même numéro forment un bloc et sont exclus du regroupement automatique.
Ordre des octets
La valeur d'un canal est découpée dans le tampon lu par le même composant que dans le
module fmProducer, le SimpleBufferPicker. byteOrder connaît donc
deux notations :
- Nommée —
bigEndian(aussibig,be,motorola,msb,network) oulittleEndian(aussilittle,le,intel,lsb). Sans indication, Big Endian s'applique. - Sous forme de correspondance — une suite de lettres qui place les octets de la valeur dans l'ordre dans lequel ils se trouvent sur le bus. La longueur de la suite indique sur combien d'octets s'étend la valeur, l'ordre des lettres indique comment les permuter.
Cela explique aussi la différence entre "AB" et "BA" : les deux décrivent une valeur sur deux
octets. "AB" les reprend dans l'ordre lu, "BA" les permute. De même pour quatre octets :
"ABCD" inchangé, "CDAB" permuté par mots, "DCBA" entièrement inversé — les quatre variantes
avec lesquelles les appareils ModBus stockent des valeurs 32 bits.
"BIT" est un cas particulier pour l'accès à un bit individuel. Une suite qui n'est ni un nom connu
ni une correspondance valide désactive le canal ; le message le désigne par son nom.
Comportement temporel et gestion des erreurs
Cycle d'interrogation
Le bus est servi par un thread dédié qui, à chaque cycle d'interrogation
(pollCycleInMilliseconds ou pollCycleInNanoseconds), lit successivement tous les blocs de registres
échus. Un bloc avec pollingIntervalMultiplicator: n n'est échu qu'à chaque n-ième cycle ; les blocs
ayant le même multiplicateur sont alors répartis sur des cycles différents, afin qu'ils ne tombent pas
tous dans le même cycle.
Un bloc qui n'est pas échu dans un cycle ne produit rien. Jusqu'à smartCORE 2.11, le contenu
inchangé du bloc était à la place émis de nouveau avec l'heure actuelle — un canal avec
pollingIntervalMultiplicator: 5 fournissait ainsi cinq fois plus de valeurs qu'il n'y avait eu de
mesures.
Horodatage des valeurs mesurées
Chaque canal porte l'horodatage de la transaction dont provient sa valeur : l'instant où la réponse de l'appareil est arrivée. Tous les canaux d'un bloc de registres portent donc le même horodatage. L'instant auquel l'appareil a formé la valeur ou l'a placée sur la ligne n'est pas observable via ModBus — l'arrivée de la réponse est l'instant le plus proche que le protocole fournisse.
Jusqu'à smartCORE 2.11, les valeurs portaient l'instant de leur sortie dans le smartCHANNEL, et non celui de la mesure — c'est-à-dire l'instant après l'interrogation de tous les appareils du bus, éventuellement avec un retard de plusieurs secondes.
Silence de trame en ModBus/RTU
Avant chaque requête, la ligne est maintenue au repos pendant la durée du silence de trame t3.5 — la pause qui sépare un message RTU du suivant. Sa durée résulte de :
| Condition | Silence |
|---|---|
readDelayMs est défini | la valeur indiquée |
| Débit supérieur à 19200 bauds (ou inconnu) | 1,75 ms — la valeur fixe de la MODBUS over Serial Line Specification V1.02 ; la valeur calculée se réduirait à 0,33 ms à 115200 bauds et ne séparerait plus rien |
| sinon | 3,5 caractères de 11 bits, soit 38500000 / débit en bauds microsecondes — 4,01 ms à 9600 bauds |
La pause se situe avant la requête. Jusqu'à smartCORE 2.11, la pause avait lieu après une réponse réussie — donc justement pas après un timeout, c'est-à-dire pas dans le cas où la ligne a le plus besoin du silence.
Deux éléments sont alors également journalisés, car ils indiquent une installation configurée trop rapidement : les octets de la requête précédente qui se trouvent encore dans la file d'émission au démarrage de la suivante (« la ligne est plus lente que ne le suppose le cycle d'interrogation »), et les données qui se trouvent de manière inattendue dans le tampon de réception. Ces dernières sont lues et signalées avec leurs premiers octets, et non rejetées silencieusement.
Timeout et désactivation d'un bloc de registres
Si une requête ne reçoit pas de réponse dans le délai timeoutInMilliseconds, l'accès est considéré
comme ayant échoué. Le bloc de registres compte ces échecs et, après
minimalChannelAlarmCount échecs consécutifs, il est désactivé : il n'est plus interrogé et ses
canaux ne produisent plus rien. Le message indique l'appareil, l'adresse de registre, le code de
fonction, la longueur de la série d'erreurs et si une nouvelle tentative est prévue.
Toutes les erreurs ne comptent pas pour ce seuil :
| Réponse de l'appareil | Effet |
|---|---|
| Pas de réponse (timeout), Illegal Function (01), Illegal Data Address (02), Illegal Data Value (03), Server Failure (04), Negative Acknowledge (07), Memory Parity (08), Gateway Target Failed To Respond (0B) | compte pour la désactivation — l'appareil ou la configuration est durablement défaillant |
| Acknowledge (05), Server Busy (06), Gateway Path Unavailable (0A) | ne compte pas — l'appareil demande de la patience |
| Trame endommagée, p. ex. erreur CRC | ne compte pas — un événement, pas un état ; répéter la requête est la bonne réponse |
retryAfterBlockFailS décide si un bloc désactivé revient : avec 0, il reste hors service pendant
toute la durée de la mesure ; avec une valeur supérieure à zéro, une nouvelle tentative a lieu après ce
délai. Si la tentative réussit, le bloc est de nouveau en service et le compteur est remis à zéro ; si
elle échoue, le temps d'attente recommence.
Un appareil qui disparaît et réapparaît occasionnellement sur le terrain a besoin de
retryAfterBlockFailS. Sans cette clé, c'est terminé après minimalChannelAlarmCount échecs,
même si l'appareil est de nouveau présent sur le bus deux minutes plus tard.
Informations sur le module
| Information | Valeur |
|---|---|
| Auteurs | optiMEAS GmbH |
| depuis smartCORE | 0.1 |
| Type de module | Producer |
| Dépendances | AUCUNE |