4 - Fonctionnalités et Configuration - Spoony 1.5 – DotVision Energy

La configuration de Spoony est réalisée grâce à des fichiers XML stockés sur la carte MicroSD accessible depuis le capot avant. Voir le paragraphe 2.4.2 pour plus de détails sur l’accès à la carte MicroSD.

Ces fichiers peuvent être modifiés de 2 manières :

En retirant la carte MicroSD de l’appareil et en l’insérant dans un ordinateur, à l’aide d’un lecteur de carte MicroSD, ou d’un lecteur de carte SD et d’un adaptateur MicroSD.
Une fois l’appareil accessible sur le réseau, la modification de la configuration peut être réalisée via l’interface Web. Se referrer au paragraphe 5.10 pour plus d’information sur la manière d’accéder à la configuration via l’interface Web.

Pour éditer des fichiers XML sur votre ordinateur, nous recommandons l’utilisation du logiciel Notepad++ ou similaire.

La carte MicroSD de l’appareil contient les dossiers suivants :

certificates : Liste des certificats approuvés pour les connexions TLS.
db : Stockage local, les fichier dans ce dossier ne doivent pas être modifiés.
firmware : Dossier de mise à jour Firmware. Les nouveaux fichiers Firmware doivent être placés dans ce dossier pour permettre la mise à jour de l’appareil. Voir le paragraphe 4.12 pour plus d’information sur la procédure de mise à jour du Firmware.
logs : Répertoire de logs. Ce répertoire est principalement pour l’usage de DotVision afin de permettre d’identifier des défauts.
measurements : Répertoire de stockage. Lieu de stockage des fichiers CSV lorsque l’appareil est configuré pour le stockage local.
system : Répertoire de configuration. L’ensemble de la configuration de l’appareil se trouve dans ce répertoire.
temp : Stockage temporaire
usr : Stockage temporaire
www : Contenu de l’interface Web.

Dans les paragraphes qui suivent, tous les chemins de fichiers indiqués sont relatifs à la racine de la carte MicroSD.

Le fonctionnement de Spoony est basé sur de multiples Services, chacun assurant une fonctionnalité de l’appareil. Le service Device est responsable de l’ensemble des autres services. Ce service détermine quels autres services sont lancés au démarrage de l’appareil.

Chaque service dispose de son propre répertoire de configuration, contenant au minimum un fichier serviceSettings.xml

Par exemple, le fichier system/services/Device/serviceSettings.xml contient la configuration du service Device, tandis que le fichier system/services/Device/Automation/serviceSettings.xml contient la configuration du service Automation, qui est un sous-service du service Device.

Tous les services de l’appareil sont des sous-services du service Device. De fait, tous les fichiers de configuration de l’appareil se situent sous le répertoire system/services/Device.

L’arbre des services est décrit par la liste ci-dessous :

Device : Service principal, contient tous les autres services
- Automation : Service d’Automation, mets à disposition les mesures (DataPoints)
- Console : Service Console, permet la gestion locale et à distance de l’appareil
- HttpServer : Serveur web
- JsonRpc : Service JSON-RPC (Remote Procedure Call)
- ModbusSerial : Service Modbus RS485 server
- ModbusTCP : Service Modbus TCP server
- MqttClient : Service MQTT Client
- NetworkManager : Service de gestion et configuration réseau
- Ntp : Service Network Time Protocol pour la synchronisation de l’horloge système
- ODM : Service d’échantillonnage et d’envoi/stockage. Basé sur 2 sous-services
  - ODMDataChunk : Service d’échantillonnage
  - ODMWebPush : Service de stockage ou d’envoi
- TimeService : Service de gestion du temps

Les paragraphes qui suivent décrivent les options de configuration disponibles pour chaque service.

La configuration par défaut de votre appareil peut différer en partie des configurations présentées ci-dessous si vous avez fait la demande d’une pré configuration particulière selon vos spécifications.

2 Device service

Le service Device est le service principal de l’appareil. C’est le service qui renferme la configuration globale, et où les autres services sont activés ou désactivés.

Fichier de configuration : system/services/Device/serviceSettings.xml

Link

Organisation du fichier de configuration :

Figure 1 – Organisation du fichier de configuration du service Device

Options de l’appareil (Device options)

Figure 2 – Service Device – Options de l’appareil (Device options)

Les caractéristiques de l’appareil peuvent être configurées depuis cette section. La plupart de ces caractéristiques sont uniquement destinées à l’affichage local sur l’interface Web. Seule l’option MyLittleSpoony doit être obligatoirement configurée, car il s’agit de l’identifiant principal de l’appareil utilisé par les autres services.

En particulier, cet identifiant est celui envoyé au serveur de stockage lorsque le service ODM est configuré pour l’envoi. Cet identifiant est également utilisé pour préfixer les noms de fichiers CSV lorsque le service ODM est configuré pour le stockage local.

2.1 Liste des services (Services list)

La liste des services contient plusieurs paramètres qui ne doivent pas être modifiés. Les paramètres modifiables sont indiqués en jaune ci-dessous.

Figure 3 - service Device – Liste des services (Services List)

3 Réseau (Network service)

La configuration réseau de l’appareil est réalisée depuis le fichier de configuration du NetworkManager.

Fichier de configuration : system/services/Device/NetworkManager/serviceSettings.xml

Link

Organisation du fichier de configuration :

Figure 4 – Organisation du fichier de configuration du Network Manager

Note : Les sections wifi et wifi-ap peuvent ne pas être disponibles si votre appareil n’est pas équipé de l’extension Wifi.

3.1 Configuration réseau câblé Ethernet

L’appareil est configuré en mode DHCP par défaut. Dans ce mode, l’adresse IP, le masque de sous-réseau, l’adresse de la passerelle ainsi que les serveurs DNS sont obtenus automatiquement depuis un serveur DHCP.

Ce mode est activé comme suit :

Figure 5 – Configuration DHCP de l’interface Ethernet

Pour configurer l’interface Ethernet en mode IP statique, la configuration suivante doit être utilisée et complétée selon vos besoins :

Figure 6 – Configuration de l’interface Ethernet en mode IP fixe

Veuillez noter que l’appareil ne supporte actuellement que la norme IPv4.

Les serveurs DNS peuvent être omis si votre appareil n’utilise pas la résolution dynamique des noms (par exemple, si l’appareil ne fonctionne qu’en mode stockage local, ou que l’adresse de destination est identifiée directement par son adresse IP).

3.2 Configuration réseau Wifi

Ce paragraphe est applicable uniquement aux appareils équipés de l’option Wifi

1.3.2.1.1 Point d’Accès Wifi

L’appareil dispose d’une fonctionnalité Point d’accès qui fonctionne directement lors du premier allumage. A l’allumage, l’appareil met à disposition un point d’accès dédié.

En vous connectant sur ce point d’accès, vous serez redirigés directement vers la page d’accueil de l’interface Web. Si ce n’était pas le cas, vous pourriez y accéder en saisissant l’adresse suivante dans votre navigateur Web. Veuillez noter que cette adresse n’est valable qu’au travers de l’interface Wifi point d’accès.

http://me.iofdevices.com

La fonctionnalité Wifi point d’accès utilise la configuration réseau ci-dessous par défaut. Si cette configuration est incompatible avec vos autres interfaces réseau (par exemple, si l’interface utilise le même sous-réseau), vous pouvez modifier ces paramètres depuis la section de configuration wifi-ap du NetworkManager ci-dessous.

Figure 7 – Configuration de l’interface Wifi point d’accès

Vous pouvez également activer la sécurité sur l’interface Wifi point d’accès en configurant un mot de passe comme indiqué. Veuillez noter que ce mot de passe doit être constitué de 8 caractères minimum.

L’interface Wifi point d’accès peut être totalement désactivée en supprimant la section de configuration montrée plus haut.

3.2.2.1 Configuration de l’interface Wifi station au travers du point d’accès

La connexion à votre réseau local au travers de l’interface Wifi peut être configurée directement depuis l’interface Web de l’appareil, accessible via le point d’accès, en particulier si votre LAN dispose de la fonctionnalité DHCP.

Dans ce cas, se référer au paragraphe 5.10.1.1.1 pour la procédure détaillée.

Si votre réseau local ne dispose pas de la fonctionnalité DHCP, merci de suivre la procédure indiquée dans le paragraphe suivant.

3.2.2.2 Configuration de l’interface Wifi station depuis le fichier de configuration

La configuration de l’interface Wifi station est réalisée depuis la section suivante du fichier de configuration du NetworkManager.

Figure 8 – Configuration de l’interface Wifi station en mode DHCP

Indiquez le nom de votre point d’accès Wifi et le mot de passe comme indiqué. Pour vous connecter à un réseau non sécurisé, le mot de passe peut être laissé vide.

Si votre réseau ne dispose pas de la fonctionnalité DHCP, ou si vous souhaitez configurer une adresse IP fixe, réglez le paramètre dhcp à false et renseignez votre configuration réseau comme indiqué ci-dessous.

Figure 9 – Configuration de l’interface Wifi station en mode IP fixe

4 Configuration du service NTP

Le service NTP (Network Time Protocol) permet la synchronisation automatique de l’horloge interne de l’appareil. Lorsqu’il est activé (par défaut), l’appareil effectue des requêtes NTP à intervalle régulier pour resynchroniser son horloge système.

Fichier de configuration : system/services/Device/Ntp/serviceSettings.xml

Link

Organisation du fichier de configuration :

Figure 10 – Configuration du service NTP

5 Configuration du service Automation

5.1 Vue globale du service Automation

Le service Automation est chargé de mettre à disposition et d’organiser les mesures de l’appareil, ainsi que les mesures d’appareils externes lues via la fonctionnalité Modbus Client.

Fichier de configuration : system/services/Device/Automation/serviceSettings.xml

Link

Organisation du fichier de configuration :

Figure 11 – Organisation du fichier de configuration du service Automation

Toutes les mesures (valeurs) disponibles au travers du Spoony sont appelées DataPoints. Un DataPoint est un objet contenant une Valeur, un Index et un Timestamp.

Le service Automation repose sur deux éléments de base : Les Automation Units (unités d’Automation) et l’Automation Index (indexe ou répertoire)

Une Automation Unit est un élément de base mettant à disposition une liste de DataPoints. Plusieurs Automation Units peuvent être déclarées, comme détaillé dans les paragraphes suivants.

L’Automation Index est un arbre d’alias utilisé pour organiser les DataPoints des différentes Automation Unit au sein d’une arborescence unique. Sa syntaxe est décrite plus loin.

Spoony contient toujours au moins 2 Automation Units de base :

ade7758 : Cette unité mets à disposition les mesures issues du circuit intégré interne de mesure d’énergie.
outputs : Cette unité met à disposition des DataPoints binaire correspondants à l’état des sorties drain ouvert de l’appareil.

D’autre types d’unités sont également disponible en option :

tic: Cette unité met à disposition les DataPoints lus au travers du démodulateur TIC connecté à un compteur d’énergie externe (voir paragraphe 3.4 pour les détails de l’entrée TIC)
soft : Cette unité met à disposition des DataPoints calculé en temps réel depuis d’autres DataPoints et est capable de calculer les valeurs moyenne, minimum et maximum.
modbus : Cette unité met à disposition des DataPoints lus depuis des appareils externes via le protocole Modbus (RS485 ou TCP)

Les options de configuration de chaque type d’unité sont détaillées dans les paragraphes suivants.

5.2 Automation Unit ADE7758

Cette unité met à disposition les mesures lues depuis le circuit intégré interne de mesure d’énergie (ADE7758). Cette unité n’accepte aucun paramètre.

L’unité doit être déclaré comme suit dans la section <units>

Figure 12 – Configuration de l’automation unit ADE7758

La calibration du circuit de mesure peut être réalisée uniquement au travers de l’interface Web. Se référer au paragraphe 5.10.6 pour plus de détails concernant la calibration de l’appareil.

Lorsqu’elle est active, cette unité expose les DataPoints suivant :

Path	Description	Unit
units/ade7758/FREQ	Line frequency, measured on L1	Hz
units/ade7758/IRMSA	RMS Current phase L1	A
units/ade7758/IRMSB	RMS Current phase L2	A
units/ade7758/IRMSC	RMS Current phase L3	A
units/ade7758/VRMSA	RMS Voltage phase L1	V
units/ade7758/VRMSB	RMS Voltage phase L2	V
units/ade7758/VRMSC	RMS Voltage phase L3	V
units/ade7758/WATTA	Active Power phase L1	W
units/ade7758/WATTB	Active Power phase L2	W
units/ade7758/WATTC	Active Power phase L3	W
units/ade7758/VARA	Reactive Power phase L1	VAR
units/ade7758/VARB	Reactive Power phase L2	VAR
units/ade7758/VARC	Reactive Power phase L3	VAR
units/ade7758/VAA	Apparent Power phase L1	VA
units/ade7758/VAB	Apparent Power phase L2	VA
units/ade7758/VAC	Apparent Power phase L3	VA
units/ade7758/PFA	Power Factor phase L1
units/ade7758/PFB	Power Factor phase L2
units/ade7758/PFC	Power Factor phase L3
units/ade7758/WATTHRA	Active Energy phase L1	Wh
units/ade7758/WATTHRB	Active Energy phase L2	Wh
units/ade7758/WATTHRC	Active Energy phase L3	Wh
units/ade7758/VARHRA	Reactive Energy phase L1	VARh
units/ade7758/VARHRB	Reactive Energy phase L2	VARh
units/ade7758/VARHRC	Reactive Energy phase L3	VARh
units/ade7758/VAHRA	Apparent Energy phase L1	VAh
units/ade7758/VAHRB	Apparent Energy phase L2	VAh
units/ade7758/VAHRC	Apparent Energy phase L3	VAh
units/ade7758/WATT	Total Active Power	W
units/ade7758/VAR	Total Reactive Power	VAR
units/ade7758/VA	Total Apparent Power	VA
units/ade7758/WATTHR	Total Active Energy	Wh
units/ade7758/VARHR	Total Reactive Energy	VARh
units/ade7758/VAHR	Total Apparent Energy	VAh

Figure 13 – DataPoints de l’unité d’automation ADE7758

5.3 Automation Unit Outputs

Cette unité donne accès aux trois sorties drain-ouvert de l’appareil au travers de DataPoints binaire. Cette unité n’accepte aucun paramètre.

Cette unité doit être déclaré dans la section <units> comme suit.

Figure 14 - Configuration de l’automation unit Outputs

Lorsqu’elle est activée, cette unité expose les DataPoints suivants :

Path	Description	Unit
units/outputs/RELAYA	Output OUTA status	Hz
units/outputs/RELAYB	Output OUTB status	A
units/outputs/RELAYC	Output OUTC status	A

Figure 15 – DataPoints de l’unité d’automation Outputs

5.4 Automation Unit TIC

Cette unité donne accès aux données lues au travers de l’interface TIC de l’appareil. Le bus TIC utilise un protocole série où les données sont envoyées en format ASCII. Référez-vous à la documentation constructeur pour plus de détails concernant ce protocole.

Cette unité doit être configuré comme indiqué ci-dessous :

Figure 16 – Configuration de l’unité d’automation TIC

La liste des DataPoints qui doivent être extraits des trames TIC entrantes doit être complètement décrite. Les valeurs qui n’apparaissent pas dans cette liste seront ignorées.

Pour chaque DataPoint, vous devez préciser :

name : Le nom local du DataPoint
tag : Le TAG correspondant dans les trames TIC entrantes
type : Le type de donnée. Seuls les types uint64, uint32 et enum sont supportés
values : Si le type est enum uniquement, la liste des valeurs possibles pour ce champ dans les trames entrantes. La valeur effective du DataPoint sera l’index de la valeur lue dans cette liste, ou -1 si la valeur reçue ne fait pas partie de la liste.

Une fois activée, les DataPoints exposés dépendent de la configuration de l’unité. Par exemple :

Path	Description	Unit
units/tic/ADCO	ADCO
units/tic/OPTARIF	OPTARIF
units/outputs/BASE	BASE

…

5.5 Automation Unit SoftAutomationUnit

Cette unité procure des fonctionnalités de calcul en permettant de réaliser des opérations arithmétiques entre des DataPoints, ainsi que des calculs de valeur moyenne, minimum et maximum sur des périodes configurables.

Exemple de configuration :

Figure 17 – Configuration de l’unité d’automation SoftAutomationUnit

Les paramètres acceptés par cette unité sont les suivants :

period : La période en ms entre 2 rafraichissement de la valeur de sortie. L’algorithme de calcul est exécuté toutes les period ms sur la liste complète des DataPoints. La plupart des DataPoints sont mis à jour toutes les secondes. En réglant ce paramètre à 1000, toutes les mises à jour des DataPoint seront prise en compte pour le calcul de la valeur de sortie.
offset : La durée en ms, à l’issue de la période, pendant laquelle le calcul est différé. (ex : Les calculs seront effectués à 00:00:00.1, 00:00:00.2 etc). Ce délai permet de prendre en compte le temps de mise à jour des DataPoints. Il est recommandé de régler ce paramètre à 1/10^e de la période de manière générale.

Pour chaque section <datapoint>, les paramètres suivants sont disponibles :

name : Nom du DataPoint. Le DataPoint sera rendu disponible sous units/soft/name
value : Expression arithmétique. Permet d’utiliser la valeur d’un autre DataPoint sous la forme DP(path/to/datapoint)
filter : Type de filtre à appliquer. Les valeurs possibles sont avg (Average), min (Minimum), max (Maximum)
sample : Nombre d’échantillons pour l’opération de filtrage. Régler ce paramètre à 1 (par défaut) permet de désactiver le filtre puisque la valeur de sortie est mise à jour à chaque échantillon d’entrée.
unit : Unité du DataPoint de sortie

5.6 Automation Unit Modbus Master (Client)

Cette unité permet la récupération de données depuis des appareils externes vers le Spoony. Une fois récupérées, ces valeurs sont disponibles comme DataPoints et peuvent être utilisées pour le calcul (Soft Unit), l’envoi ou le stockage au travers du service ODM.

Attention : Lorsque le bus RS485 est utilisé pour la fonctionnalité Modbus Master comme décrit ci-dessous, il ne peut être utilisé pour la fonctionnalité Modbus Slave et le service ModbusSerial DOIT être désactivé pour permettre un fonctionnement normal. Modbus TCP peut en revanche être utilisé simultanément pour les fonctionnalités Master et Slave.

Ce paragraphe couvre la configuration de l’unité d’automation Modbus Master, qui est basée sur des fichiers de modèle (Device Models) et de politique de mise à jour (Update Policies). Se référer à la section 01.6 pour plus de détails concernant la création de fichiers de modèles et de politique de mise à jour.

L’unité Modbus Master nécessite la configuration de la couche de transport correspondante dans un premier temps. Cette entrée de configuration doit être renseignée dans la section <transports> et est dépendante du type de transport utilisé (RS485 ou TCP)

Pour RS485, l’entrée <transport> est configurée comme indiqué ci-dessous.Figure 18 – Configuration du transport Modbus RS485

Note : Une seule entrée transport de type RS485 peut être créée.

Pour TCP, l’entrée <transport> est configurée comme indiqué ci-dessous.

Figure 19 – Configuration du transport Modbus TCP

Une fois la section de transport correctement configurée, l’unité ModbusUnit peut être configurée et reliée à la couche de transport correspondante.

Une seule unité Modbus peut communiquer avec de multiples esclaves et est configurée comme indiqué ci-dessous.

Figure 20 – Configuration de l’unité Modbus

Dans le cas d’un transport TCP, chaque unité Modbus peut communiquer avec un seul destinataire. Si vous devez communiquer avec plusieurs destinataires, vous devrez déclarer autant de Transports et d’unité Modbus que nécessaire. Le champ destination doit être réglé à 0 dans la plupart des cas, à moins que l’appareil ciblé ne dispose de fonctionnalités Modbus Gateway.

Chaque Transport et ModbusUnit déclaré DOIT avoir un nom unique.

La liste des DataPoints exposée par l’unité dépendra de la configuration et des modèles utilisés. Chaque modèle déclare une liste de DataPoints identifiés par un nom unique. Chaque unité Modbus exposera ces DataPoints, préfixés de la destination Modbus comme suit :

Figure 21 – Format des noms de DataPoint Modbus

5.7 Index de l’Automation Space

La section <index> de l’Automation Space permet d’identifier tous les DataPoints des différentes unités à travers une arborescence unique (arbre d’alias ou répertoire).

L’adressage des DataPoint peut être réalisé au travers de leur chemin par défaut (units/{unit name}/{datapoint name}) ou d’un Alias déclaré dans l’Index.

Cet indexe se présente sous la forme d’un arbre pour organiser facilement les DataPoints. L’index par défaut est présenté ci-dessous. Les DataPoints d’autres unités peuvent être ajoutés à l’index selon les besoins. Cet index est essentiellement utilisé pour organiser la navigation dans les DataPoints depuis l’interface Web et l’API.

Figure 22 – Configuration par défault de l’Indexe de l’Automation Space

6 Configuration Modbus

Ce chapitre couvre en détail les différentes fonctionnalités Modbus de l’appareil. Ceci inclus les fonctionnalités Modbus Master (Client) et Slave (Server), via RS485 et TCP.

6.1 Vue globale des fonctionnalités Modbus de l’appareil

L’appareil offre 2 modes d’opération :

Modbus Slave (Server) : Ce mode permet l’accès aux DataPoints de l’appareil via Modbus RS485 ou TCP.
Modbus Master (Client) : Ce mode permet d’accéder aux données d’appareils externe compatibles Modbus pour permettre l’agrégation de données dans le Spoony.

Le mode Modbus Master est configuré depuis le service Automation comme décrit dans le paragraphe 1.5.6. Le paragraphe 0 décrit la création de fichier de modèles et de politique de mise à jour.

6.2 Modbus Slave (Server)

La fonctionnalité Modbus Slave est disponible via RS485 et TCP. Les deux fonctionnalités sont couvertes par un service différent dont la configuration est proche. Cette section couvre les portions similaires des 2 fichiers de configuration.

Fichier de configuration : system/services/Device/ModbusTCP/serviceSettings.xml et system/services/Device/ModbusSerial/serviceSettings.xml

Link1 Link2

Organisation des fichiers de configuration :

Figure 23 – Organisation du fichier de configuration Modbus Slave

Le mapping des registres Modbus (section <model>) est similaire pour les modes TCP et RS485 et détermine le mapping entre les registres Modbus exposés par l’appareil et les DataPoints du service Automation.

Tous les DataPoints peuvent être exposés au travers de l’interface Modbus Slave, incluant les DataPoints lus depuis d’autres appareils Modbus ainsi que les DataPoints calculés, offrant une grande flexibilité.

La section <model> est organisée comme suit.

Figure 24 - Mapping Modbus par défaut de l’appareil

Ce modèle distingue les différents types de registres Modbus : Holding registers (Lecture/Ecriture), Input registers (Lecture seule), Coil registers (Lecture/Ecriture binaire) et Discrete Inputs (Lecture seule binaire).

Chaque entrée de type Holding ou Input dispose des paramètres suivants :

address : Adresse du registre Modbus
size : La taille, en nombre consécutif de registres 16 bits. Tous les DataPoints du Spoony sont de type virgule-flottante à l’exception des DataPoints binaires, et doivent être mappés sur 2 registres consécutifs.
datapoint : Chemin du DataPoint, par Alias ou Absolu.

Chaque entrée de type Coil or Discrete Input dispose des paramètres suivants :

address : L’adresse Modbus de l’entrée Coil/Discrete
datapoint : Chemin vers le DataPoint, par Alias ou Absolu.

Pour des raisons de compatibilité, même si la table d’adressage Modbus peut être modifiée par l’utilisateur final, DotVision recommande de conserver la table d’adressage par défaut et d’ajouter de nouvelles entrées pour exposer des DataPoints supplémentaires, ou créer des groupes DataPoints sur des adresses consécutives par exemple.

6.3 Spécificités du mode Modbus Slave (Server) RS485

Les paramètres spécifiques au mode RS485 sont indiqués ci-dessous. Ces paramètres s’appliquent uniquement au service ModbusSerial

Figure 25 – Configuration spécifique au mode Modbus slave RS485

6.4 Spécificités du mode Modbus Slave (Server) TCP

Les paramètres spécifiques au mode TCP sont indiqués ci-dessous. Ces paramètres s’appliquent uniquement au service ModbusTCP.

Figure 26 – Configuration spécifique au mode Modbus slave TCP

6.5 Table Modbus par défaut

La table suivante décrit le mapping Modbus par défaut de l’appareil.

Input registers
Register address	Register name	Description
0x0000	FREQ	Line Frequency (Hz)
0x0002	VRMSA	VRMS Phase L1 (Vrms)
0x0004	VRMSB	VRMS Phase L2 (Vrms)
0x0006	VRMSC	VRMS Phase L3 (Vrms)
0x0008	IRMSA	IRMS Phase L1 (Arms)
0x000A	IRMSB	IRMS Phase L2 (Arms)
0x000C	IRMSC	IRMS Phase L3 (Arms)
0x000E	WATTA	Active power Phase L1 (W)
0x0010	WATTB	Active power Phase L2 (W)
0x0012	WATTC	Active power Phase L3 (W)
0x0014	WATT	Total Active Power (W)
0x0016	VAA	Apparent power Phase L1 (VA)
0x0018	VAB	Apparent power Phase L2 (VA)
0x001A	VAC	Apparent power Phase L3 (VA)
0x001C	VA	Total Apparent Power (VA)
0x001E	VARA	Reactive power Phase L1 (VAR)
0x0020	VARB	Reactive power Phase L2 (VAR)
0x0022	VARC	Reactive power Phase L3 (VAR)
0x0024	VAR	Total Reactive Power (VAR)
0x0026	PFA	Power Factor Phase L1
0x0028	PFB	Power Factor Phase L2
0x002A	PFC	Power Factor Phase L3
0x002C	AWATTHR	Active Energy Phase L1 (WH)
0x002E	BWATTHR	Active Energy Phase L2 (WH)
0x0030	CWATTHR	Active Energy Phase L3 (WH)
0x0032	WATTHR	Total Positive Active Energy (WH)
0x0034	AVAHR	Apparent Energy Phase L1 (VARH)
0x0036	BVAHR	Apparent Energy Phase L2 (VARH)
0x0038	CVAHR	Apparent Energy Phase L3 (VARH)
0x003A	VAHR	Total Apparent Energy (VARH)
0x003C	AVARHR	Reactive Energy Phase L1 (WH)
0x003E	BVARHR	Reactive Energy Phase L2 (WH)
0x0040	CVARHR	Reactive Energy Phase L3 (WH)
0x0042	VARHR	Total Reactive Energy (WH)
Coil registers
Register address	Register name	Description
0x0000	RELAYA	Open-drain output OUTA status
0x0001	RELAYB	Open-drain output OUTB status
0x0002	RELAYC	Open-drain output OUTC status

Figure 27 - Default Modbus address map

6.6 Modbus Master (Client) RS485 et TCP

La configuration de base du mode Modbus Master est décrite en détail dans le paragraphe 1.5.6. Le paragraphe qui suit décrit le format des fichiers de Modèle d’appareil (Device model) et de Politique de mise à jour (Update policies). Ces fichiers sont référencés par l’unité d’automation Modbus et décrivent le contenu des appareils Modbus externes.

6.6.1.1 Fichier de configuration – Modèle d’appareil

Un fichier de configuration de modèle d’appareil est une liste exhaustive des DataPoints Modbus qui doivent être lus depuis un appareil compatible Modbus. Seuls les DataPoints décris dans le fichier de modèle seront lus par l’unité d’automation Modbus.

La fréquence à laquelle ces lectures sont effectuées est déterminée par le fichier de configuration de la Politique de mise à jour, décris dans le paragraphe suivant.

Les fichiers de modèle d’appareil Modbus doivent être placés dans le répertoire system/services/Device/Automation/models et sont au format suivant.

Figure 28 – Fichier de modèle d’appareil Modbus

Les DataPoints externes sont organisés en groupes (maps), ou chaque groupe correspond à une plage de registres Modbus qui seront lu à l’aide d’une unique requête de lecture. Ceci permet une grande flexibilité mais requiert quelques précautions.

Vous devez éviter de créer des groupes (maps) qui couvre une large plage d’adresses Modbus. Par exemple, si vous souhaitez lire les registres 1 et 200 d’un appareil externe, créez 2 groupes différents. Sinon, cela résultera en une unique lecture Modbus de 200 registres, ce qui causerait un trafic important sur le bus.

En revanche il est acceptable d’avoir des groupes contenants 2 ou 3 registres dont les valeurs sont ignorées, puisqu’il est plus efficace de lire ces registres et d’en ignorer le contenu (ce que fait Spoony) plutôt que d’effectuer 2 requêtes de lecture successives.

Un groupe (map) se présente comme suit.

Figure 29 – Groupe d’un modèle d’appareil Modbus

Chaque groupe dispose de plusieurs paramètres qui doivent être correctement configurés, ainsi que d’une liste de DataPoints.

Les paramètres du groupe (map) sont les suivants :

name : Chaque groupe DOIT être nommé. Ce nom servira d’identifiant depuis le fichier de Politique de mise à jour. Le nom DOIT être unique au sein d’un modèle d’appareil Modbus.
type : Indique le type de registre Modbus sous-jacent. Les types possibles sont holdingRegister, inputRegister, discretesInput et coil
swap : Indique le mode de swap par défaut du groupe. Ce mode par défaut peut être modifié sur chaque entrée datapoint si nécessaire. Les valeurs possibles sont none, bw (bytes et words), b (bytes) et w (words)
count : Le nombre d’entrées dans le groupe. Ce paramètre DOIT correspondre au nombre exact d’entrées <datapoint> dans le groupe.

Chaque entrée datapoint du groupe accepte les paramètres suivants :

address : Adresse du registre Modbus
size : Nombre de registres Modbus consécutifs
name : Nom du DataPoint. Ce nom est utilisé pour identifier le DataPoint au sein de la unit comme indiqué dans la Figure 21 – Format des noms de DataPoint Modbus
format : Format des données dans l’appareil distant. Les valeurs possibles sont int16 (entier signé 16 bits), uint16 (entier non signé 16 bits), int32 (entier signé 32 bits), uint32 (entier non signé 32 bits) et float (Virgule flottante IEE 754)
swap : Mode de swap. Les valeurs possibles sont none, bw (bytes et words), b (bytes) et w (words)
factor : En option. Facteur de conversion (multiplicateur) à appliquer sur les données lues.

Une fois le modèle d’appareil complet, vous devez créer un fichier de Politique de mise à jour correspondant pour définir à quelle fréquence chaque groupe (map) sera mise à jour.

6.6.1.2 Fichier de configuration de la Politique de mise à jour Modbus de l’appareil

Les fichiers de configuration de la Politique de mise à jour Modbus sont attachés à chaque fichier de modèle d’appareil Modbus et décrivent quand les groupes définis dans le modèle doivent être mis à jour (lus) depuis l’appareil externe.

Le format de ces fichiers est décrit ci-dessous.

Figure 30 – Organisation des fichiers de configuration de la Politique de mise à jour Modbus du modèle d’appareil

Ces fichiers contiennent une liste de groupes. Chaque groupe DOIT contenir un trigger qui spécifie QUAND les groupes (maps) correspondantes doivent être mise à jour, ainsi que liste d’entrée <add></add> spécifiant quels groupes (maps) en font partie.

La configuration du trigger de type TimeTrigger est constituée d’un entier, suivi d’une configuration d’unité (-U) et d’un mode (-M)

Les unités valides sont s (secondes) et m (minutes). Le mode DOIT toujours être absolute.

Par exemple, la configuration suivante :

30 -U:s -M:absolute

Indique que les groupes doivent être mis à jour toutes les 30 secondes.

Une fois vos fichiers de Modèle et de Politique définis, ils doivent être placés dans le répertoire system/services/Device/Automation/models. Ils peuvent être référencés depuis cet emplacement dans la configuration des unités d’Automation Modbus comme indiqué dans le paragraphe 1.5.6

7 Configuration du service ODM (stockage et envoi de données)

7.1 Généralités

Le service ODM est chargé d’échantillonner les DataPoints exposés par le service Automation, pour les envoyer vers un serveur ou les stocker dans des fichiers CSV.

La configuration diffère en fonction du mode souhaité (stockage ou envoi) et est détaillée dans les paragraphes qui suivent.

L’architecture du service ODM est décrite dans le diagramme ci-dessous.

Figure 31 – Architecture du service ODM

Le service DataChunk est responsable de l’échantillonnage des DataPoints à intervalle défini, et de la construction de DataChunks.

Les DataChunks sont un format d’objet propriétaire DotVision destinés à contenir des données de séries temporelles.

Deux versions du service DataChunk sont disponibles. La version 1 est destinée au stockage local (CSV) tandis que la version 2 est destinée à l’envoi vers un serveur.

Les spécifications du format DataChunk sont détaillées dans le chapitre 6.

7.2 Configuration pour le stockage CSV local

La version 1 du service DataChunk est désormais réservée pour une utilisation en stockage local. Pour tous les autres modes d’opération, se référer au paragraphe -.

Les fichiers CSV générés dans ce mode sont sauvegardés dans le dossier measurements et nommés suivant le modèle ci-dessous :

{MyLittleSpoony}_YYYY-MM-DD_HH-mm.csv

Figure 32 – Convention de nommage des fichiers CSV

Avec :

{MyLittleSpoony} : Le nom de l’appareil tel que configuré dans le service Device. Voir le paragraphe 2 pour plus d’information.
YYY-MM-DD_HH-mm : Date et heure du début de période

7.2.1.1 Configuration du service ODM

Le service ODM doit être configuré pour utiliser la version 1 du service DataChunk ainsi que le service CsvLogService comme indiqué ci-dessous.

Fichier de configuration : system/services/Device/ODM/serviceSettings.xml

Link

Figure 33 – Fichier de configuration principal du service ODM pour le mode stockage CSV local

7.2.1.2 Configuration du service ODMWebPush en mode Log CSV

En mode stockage CSV, le service ODMWebPush est de type CsvLogService et utilise le format de configuration suivant.

Fichier de configuration : system/services/Device/ODM/ODMWebPush/serviceSettings.xml

Link CSV

Figure 34 – Configuration du service ODMWebPush pour le stockage local en CSV

Les paramètres suivants sont accessibles :

metrics : Durée des fichiers de sortie. Entier suivi de l’unité associée (s pour secondes ou h pour heures). Un nouveau fichier sera créé chaque fois que la métrique expire. Dans cet exemple, un nouveau fichier est créé tous les jours à 00:00 UTC
decimal_separator : Caractère utilisé comme séparateur de décimales
separator : Caractère utilisé comme séparateur de champs

Le paramètre path est le répertoire de sortie dans lequel seront créé les fichiers CSV et ne doit pas être modifié.

7.2.1.3 Configuration du service ODMDataChunk (Version 1)

Le stockage CSV local se base sur la version 1 du service Datachunk. Cette version dispose de moins d’options que la version 2 mais convient mieux au mode de stockage CSV car tous les DataPoints sont échantillonnés à la même fréquence.

Fichier de configuration : system/services/Device/ODM/ODMDataChunk/serviceSettings.xml

Link V1 DataChunk

Figure 35 – Configuration du service ODMDataChunk pour le stockage local CSV

Ce fichier spécifie essentiellement un paramètre :

samplingPeriod : Période d’échantillonnage en secondes.

Suit ensuite une liste de DataPoints dans la section <datapoints>.

Chaque entrée <datapoint> comporte les paramètres suivants :

path : Chemin du DataPoint, absolu ou par alias
alias : Nom optionnel qui apparaitra en tête du fichier CSV pour la colonne correspondante. Si ce paramètre est omis, le nom du DataPoint sera utilisé par défaut.

7.3 Configuration pour l’envoi de données

Pour les modes autre que le stockage local en CSV, le service DataChunk doit être configuré en version 2. Le fichier de configuration principal du service ODM doit être configuré comme suit.

Fichier de configuration : system/services/Device/ODM/serviceSettings.xml

Link

Figure 36 – Fichier de configuration principal du service ODM en mode envoi de données

7.3.1.1 Configuration du service DataChunk (version 2)

La version 2 du service DataChunk offre des fonctionnalités d’échantillonnage plus souple et d’agrégation (calcul de valeur moyenne, minimale, maximale) des DataPoints.

Il est configuré comme suit.

Fichier de configuration : system/services/Device/ODM/ODMDataChunk/serviceSettings.xml

Link V2 DataChunk

Figure 37 – Configuration du service DataChunk version 2 pour l’envoi de données

Le paramètre samplingPeriod défini à la fois la période d’envoi (intervalle entre les DataChunks) et la période d’échantillonnage par défaut pour l’ensemble des DataPoints. Chaque DataPoint peut ensuite préciser sa propre fréquence d’échantillonnage si souhaité, autorisant des fréquences supérieures ou inferieures à la fréquence par défaut.

Chaque entrée <datapoint> est ensuite définie au format suivant :

Figure 38 – Format des entrées <datapoint> pour le service DataChunk version 2

Les entrées <datapoint> acceptent les paramètres suivants :

path : Chemin du DataPoint, absolu ou alias.
unit : Unit de sortie dans le DataChunk. Les DataPoints sont groupés par Unit dans les DataChunks. Voir les spécifications détaillées du format DataChunk chapitre 6 pour plus d’information.
alias : Alias dans le DataChunk de sortie. Si omis, le nom du DataPoint sera utilisé par défaut.
period : Option pour remplacer la période d’échantillonnage par défaut. Le format DatachunkV2 autorise chaque DataPoint à disposer de sa propre fréquence d’échantillonnage. Exprimé en millisecondes.
agg_period : Option pour activer la fonction d’agrégation. Si cette valeur est présente et différente de 0, les valeurs Moyenne, Minimale et Maximale seront calculées. La valeur calculée est mise à jour à partir d’échantillons pris toutes les agg_period agg_period est généralement un sous-multiple de la fréquence d’échantillonnage du DataPoint. La valeur moyenne est envoyée comme valeur (value) dans le DataChunk de sortie. Les valeur Minimum et Maximum sont envoyées comme min et max dans le champ d’extension.
agg_offset : Uniquement actif si agg_period est présent et différent de 0. Indique le délai en ms avant l’échantillonnage. Ce paramètre permet de délayer l’échantillonnage pour prendre en compte la durée de mise à jour des DataPoints.

Précisions sur les paramètres agg_period et agg_offset:

La fréquence de sortie effective du DataPoint concerné sera soit le paramètre period si précisé, soit le samplingPeriod global par défaut.

agg_period indique la fréquence à laquelle l’algorithme d’agrégation est exécuté. Par exemple, si la period est 10000 (10s) et que agg_period vaut 1000 (1s), les valeurs moyenne, minimale et maximales seront calculées sur 10 échantillons mesurés toutes les 1s.

agg_offset permet d’introduire un délai après la période pour prendre en compte la durée de mise à jour des DataPoints.

Les valeurs des DataPoints sont généralement mise à jour toutes les secondes, et la mise à jour peut prendre jusqu’à 5ms. Généralement, agg_offset doit être réglé à 5ms.

Quand des DataPoints Modbus sont présents, leur mise à jour peut prendre plus longtemps, ce qui requiert de régler la durée agg_offset à une valeur supérieure (généralement 100 à 200ms mais dépendant du nombre et de la longueur des requêtes Modbus).

7.3.1.2 Configuration du service WebPush (envoi de données)

Le service WebPush reçoit les DataChunks de la part du service DataChunk et est responsable de leur envoi selon les paramètres configurés.

Les dernières révisions du Firmware supportent uniquement l’envoi via MQTT. Pour de l’aide sur les révisions précédentes et les protocoles précédemment supportés, ou la compatibilité avec d’autre protocoles, prendre contact avec DotVision directement.

Le service WebPush est configuré pour l’envoi via MQTT de la manière suivante.

Fichier de configuration : system/services/Device/ODM/ODMWebPush/serviceSettings.xml

Link MQTT

Figure 39 -Configuration du service WebPush pour l’envoi de données

Note : Le service MqttClient DOIT également être correctement configuré et activé pour permettre l’envoi de données. Se référer à la section 1.8 pour les détails concernant la configuration du service MQTT.

Les DataChunks sont envoyés au server MQTT selon le format spécifié dans le Chapitre 6.

8 Configuration du client MQTT

8.1 Aperçu des fonctionnalités du client MQTT

Le client MQTT intégré à l’appareil est un client MQTT 3.1 qui supporte les couches de transport TCP et TLS. Toutes les options de connexion (CONNECT MQTT) sont pleinement configurables.

Se référer à la dernière version de la documentation MQTT 3.1 disponible sur https://mqtt.org/ pour les spécifications détaillées du protocole MQTT.

Le client MQTT doit être correctement configuré pour permettre au service ODM (si configuré pour l’envoi via MQTT) ainsi qu’au service JsonRpc de fonctionner correctement.

DotVision dispose de solution cloud ou on-premise de broker MQTT et de stockage de données. Contactez DotVision pour toute question relative aux plateformes de Devices.

8.2 Configuration du client MQTT

Le client MQTT est totalement configuré depuis le fichier de configuration du service MqttClient

Fichier de configuration : system/services/Device/MqttClient/serviceSettings.xml

Link

Figure 40 – Fichier de configuration du service MqttClient

Les paramètres suivants sont disponibles :

host : Spécifier le schéma (tcp ou tls) suivi de l’hôte et du port au format {scheme}://{host}:{port}

Note : Lorsque TLS est utilisé pour la connexion, le certificat de l’Autorité de Certification Racine correspondant au format X509 DOIT être placé dans le répertoire certificates de l’appareil.

clientId : Vous pouvez spécifier un Client ID statique dans ce champ. Si omis, le GUID de l’appareil sera utilisé. Veuillez noter que la plupart des broker MQTT n’acceptent pas la connexion simultanée de 2 client avec le même Client ID.
version : Toujours 0, Version MQTT annoncée dans le requête CONNECT. Ne pas modifier
username : Nom d’utilisateur si requis
password : Mot de passe si requis
readTimeout : Temps maximum à attendre les réponses du serveur en ms. 2000ms par défaut.
willTopic : Last Will topic
willMessage : Last Will message
willQos : Last Will QOS
keepAliveInterval : Intervalle entre les requêtes PING.
cleanSession : true par défaut.

Note : Les valeurs optionnelles peuvent être laissées vides, commentée ou supprimées.

9 Serveur HTTP

9.1 Vue globale de la fonctionnalité serveur http

Le serveur http intégré à l’appareil est responsable de la mise à disposition des pages web HTML à votre navigateur, ainsi que de l’API web permettant à votre navigateur d’interagir avec l’appareil.

La configuration du serveur http ne doit pas être modifiée. Si vous avez un besoin spécifique concernant la configuration du serveur http, veuillez contacter DotVision.

10 JSON-RPC

10.1 Vue globale de la fonctionnalité JSON-RPC

Le service JSON-RPC permet d’interagir avec l’appareil grâce au protocole JSON-RPC.

Toutes les API http disponible actuellement seront disponibles au travers de Json-RPC dans les révisions future du Firmware. Json-RPC permet un haut niveau de standardisation des fonctions d’API et une interface uniforme.

Le service JSON-RPC expose les méthodes Json-RPC via http et MQTT, permettant une intégration transparente d’appareil, localement ou à distance, au travers d’une interface uniforme.

Se référer au document « JSON-RPC over MQTT & HTTP implementation by BluePanda Devices – Spoony specific methods » pour plus d’informations sur les interfaces Json-RPC des appareils DotVision.

Cette fonctionnalité est activement en cours de développement et sera amenée à évoluer sur les prochaines révisions du firmware.

10.2 Configuration du service JSON-RPC

Le service Json-RPC contient un unique paramètre de configuration qui permet de définir le topic MQTT de base pour les requêtes Json-RPC via MQTT. Ce paramètre est sans effet pour les requêtes Json-RPC via http.

Fichier de configuration : system/services/Device/JsonRpc/serviceSettings.xml

Link

Figure 41 – Fichier de configuration du service Json-RPC

11 Service Console

Le service Console est destiné à l’usage de l’équipe de maintenant et de support de DotVision et procure un accès bas niveau à l’appareil via une connexion Série, TCP et TLS (à distance) en option.

Ce service est configuré pour se connecter aux serveurs de gestion à distance de DotVision par défaut.

Cette connexion permet à l’équipe support de DotVision d’accéder à la configuration de votre appareil à distance sur votre demande, et nécessite une configuration réseau valide de votre appareil, ainsi qu’un accès internet au travers de votre réseau.

Cette connexion est totalement sécurisée par TLS et peut être désactivée depuis le fichier de configuration du service Console si nécessaire.

Merci de noter cependant que cette connexion permet à l’équipe support de DotVision de vous assister au mieux, permettant souvent la résolution de problèmes simples en quelques minutes. L’équipe support DotVision n’accèdera jamais à votre appareil sans demande de votre part. Notez également que cette connexion ne permet que l’accès à votre appareil DotVision et en aucun cas aux autres appareils de votre réseau.

Cette fonctionnalité peut être désactivée avant livraison de l’appareil sur demande de votre part.

Fichier de configuration : system/services/Device/Console/serviceSettings.xml

Link

Figure 42 – Fichier de configuration du service Console

12 Mise à jour Firmware (logiciel embarqué) de l’appareil

Le Firmware de l’appareil peut être mis à jour en plaçant le nouveau fichier Firmware (fichier .hex ou .bin) dans le répertoire firmware de la carte MicroSD avant de redémarrer l’appareil.

Au redémarrage, l’appareil va automatiquement vérifier le fichier et se mettre à jour.

Merci de noter que dans quelques cas, la mise à jour Firmware peut nécessiter également la mise à jour de certains fichiers de configuration pour permettre le bon fonctionnement de l’appareil. Si tel est le cas, vous en serez informé par DotVision lors du téléchargement de la nouvelle révision du Firmware.

Deux méthodes permettent de copier le nouveau fichier Firmware sur la carte MicroSD de l’appareil.

12.1 Copie en accédant directement à la carte MicroSD

Cette méthode est la plus rapide, mais nécessite un accès physique à l’appareil.

Retirer la carte MicroSD de l’appareil, comme indiqué dans le paragraphe 2.4.2
Insérer la carte MicroSD dans un ordinateur et copier le fichier .hex dans le répertoire firmware
Réinstallez la carte MicroSD dans l’appareil et pressez le bouton Reset. Voir paragraphe 2.4.2 pour savoir comment accéder au bouton Reset.
Après 2 minutes environ, l’appareil va redémarrer avec la nouvelle version installée. La version installée du Firmware peut être vérifiée depuis la page « Device information » de l’interface Web. Voir 5.5

12.2 Copie via l’interface Web

Le nouveau fichier Firmware peut également être uploadé via l’interface Web de l’appareil. Voir le chapitre 5.10.4 pour des instructions détaillées sur la manière de copier un fichier sur l’appareil via l’interface Web et de le redémarrer.

12.3 Restauration de la configuration d’usine

L’appareil peut être remis en configuration par défaut en effaçant l’intégralité du contenu de la carte MicroSD et en le remplaçant par le contenu de l’archive procurée par DotVision.

Retirer la carte MicroSD de l’appareil, comme indiqué dans le paragraphe 2.4.2.
Formater la carte MicroSD en utilisant le type de système de fichier FAT32. Un formatage rapide peut être utilisé.
Extraire l’ensemble de l’archive à la racine de la carte MicroSD. Le contenu de la carte MicroSD devrait ressembler à ceci :

Figure 43 – Vue du contenu de la carte MicroSD après une remise en configuration d’usine

1. Réinstaller la carte MicroSD dans l’appareil et presser le bouton Reset. Voir paragraphe 2.4.2 pour savoir comment accéder au bouton Reset.
2. Après 2 minutes environ, l’appareil va redémarrer avec la nouvelle version installée. La version installée du Firmware peut être vérifiée depuis la page « Device information » de l’interface Web. Voir 5.5

Figure 1 – Organisation du fichier de configuration du service Device.

Figure 2 – Service Device – Options de l’appareil (Device options).

Figure 3 - service Device – Liste des services (Services List).

Figure 4 – Organisation du fichier de configuration du Network Manager.

Figure 5 – Configuration DHCP de l’interface Ethernet.

Figure 6 – Configuration de l’interface Ethernet en mode IP fixe.

Figure 7 – Configuration de l’interface Wifi point d’accès.

Figure 8 – Configuration de l’interface Wifi station en mode DHCP.

Figure 9 – Configuration de l’interface Wifi station en mode IP fixe.

Figure 10 – Configuration du service NTP.

Figure 11 – Organisation du fichier de configuration du service Automation.

Figure 12 – Configuration de l’automation unit ADE7758.