Aller au contenu principal

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ètreRequisType de donnéesPlage de valeurs pertinenteDéfautDescription
versionOUIINT1Version du protocole ModBus
typeOUISTRING"modbus"Interface série pour la communication
enableOUIBOOLtrueCommutateur pour la production des données dans des smartCHANNELs
pollCycleInMillisecondsOUIINT1 -Intervalle d'interrogation [ms] des accès ModBus
transportOUIObjet JSONConfiguration de la couche de transport ModBus (voir ci-dessous)
devicesOUITableau JSON d'objets JSONListe des participants ModBus
pollCycleInNanosecondsNonINT1 -100000000Intervalle d'interrogation [ns]. Si la clé est définie, elle a priorité sur pollCycleInMilliseconds. Si les deux sont absentes, 100 ms sont utilisées
enableInternalDataReductionNonBOOLtrue, falsefalseAssocie à 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
autoGroupNonBOOLtrue, falsetrueRegroupe automatiquement les registres voisins d'un appareil en blocs de registres lus en une seule transaction (voir Blocs de registres)
autoGroupAllowGapsNonBOOLtrue, falsefalseAutorise 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
maxRegisterGroupNonINT1 - 125125Nombre 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
useF23withoutOutputsNonBOOLtrue, falsefalseUtilise le code de fonction 23 (Read/Write Multiple Registers) même lorsqu'il n'y a rien à écrire (à partir de smartCORE 2.12)
minimalChannelAlarmCountNonINT1 -2Nombre d'échecs immédiatement consécutifs après lequel un bloc de registres est désactivé (voir Timeout et désactivation)
retryAfterBlockFailSNonINT0 -0Temps 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)
workloadAsChannelNonBOOLtrue, falsefalseCrée un canal de diagnostic qui indique la charge du bus
workloadChannelBuffersizeNonINT1 -100Taille du tampon du canal de charge du bus, en éléments
workloadChannelNonSTRING ou objet JSONNom ou définition complète du canal de charge du bus

Paramètres de transport spécifiques à ModBus/TCP ("transport")​

Nom du paramètreRequisType de donnéesPlage de valeurs pertinenteDéfautDescription
typeOUISTRING"tcp"Sélection de ModBus/TCP
ipAddressOUISTRINGAdresse IP valideAdresse IP de l'appareil ModBus
ipPortNumberOUIINTNuméro de port IP valideNuméro de port IP de l'appareil ModBus (à régler sur 502, sauf indication contraire)
timeoutInMillisecondsOUIINT1 -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ètreRequisType de donnéesPlage de valeurs pertinenteDéfautDescription
typeOUISTRING"rtu"Sélection de ModBus/RTU
baudRateOUIINTDébit en bauds ModBus valideDébit en bauds de l'interface série
dataBitsOUIINT5 - 8Bits de données de l'interface série
parityOUISTRING"no", "even", "odd"Parité de l'interface série
stopBitsOUIDOUBLE1.0, 1.5, 2.0Bits d'arrêt de l'interface série
portNameOUISTRINGFichier de périphérique valideFichier de périphérique de l'interface série
timeoutInMillisecondsOUIINT1 -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()
deviceTimeoutInMillisecondsNonINT0 -0Timeout supplémentaire [ms] entre les interrogations de participants ModBus différents
readDelayMsNonINT0 -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ètreRequisType de donnéesPlage de valeurs pertinenteDéfautDescription
enableOUIBOOLtrueCommutateur d'activation de l'appareil ModBus
deviceNameOUISTRINGNom de l'appareil ModBus
deviceAddressOUIINT1 -Adresse de l'appareil ModBus
readChannelsOUITableau JSON d'objets JSONvoir 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ètreRequisType de donnéesPlage de valeurs pertinenteDéfautDescription
nameOUISTRINGNom du smartCHANNEL
addressOUIINTAdresse du registre ModBus
registerTypeOUISTRINGType de registre ModBus valideType du registre ModBus ("InputReg", "HoldingReg", "Coil", "Status", "0x17" (lecture seule))
registerFormatOUISTRINGFormat de registre ModBus valideFormat du registre ModBus ("I8","I16","I32","I64","UI8","UI16","UI32","UI64","REAL","BOOL")
byteOrderOUISTRINGvoir ci-dessousOrdre des octets de la valeur, voir Ordre des octets
bitOffsetOUIUINTDécalage en bits de la valeur à interpréter
unitOUISTRINGUnité du smartCHANNEL
scaleOUIDOUBLEMise à l'échelle du smartCHANNEL
offsetOUIDOUBLEOffset du smartCHANNEL
enableNonBOOLtrue, falsetrueUn canal avec false n'est ni créé ni lu
pollingIntervalMultiplicatorNonINT1 -1Le bloc de registres de ce canal n'est lu qu'à chaque n-ième cycle d'interrogation
registerGroupNonINT0 -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 maxRegisterGroup registres, ou
  • le registre suivant ne suit pas immédiatement le précédent et autoGroupAllowGaps vaut false.

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 (aussi big, be, motorola, msb, network) ou littleEndian (aussi little, 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.

Comportement modifié à partir de smartCORE 2.12

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.

Comportement modifié à partir de smartCORE 2.12

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 :

ConditionSilence
readDelayMs est définila 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
sinon3,5 caractères de 11 bits, soit 38500000 / débit en bauds microsecondes — 4,01 ms à 9600 bauds
Comportement modifié à partir de smartCORE 2.12

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'appareilEffet
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 CRCne 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.

astuce

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​

InformationValeur
AuteursoptiMEAS GmbH
depuis smartCORE0.1
Type de moduleProducer
DépendancesAUCUNE