{"id":21,"date":"2015-05-28T13:23:53","date_gmt":"2015-05-28T13:23:53","guid":{"rendered":"http:\/\/stateoftheartsoftware.com\/docs\/?page_id=21"},"modified":"2015-06-02T16:36:48","modified_gmt":"2015-06-02T16:36:48","slug":"file-format-user-defined-modbus-devices","status":"publish","type":"page","link":"https:\/\/stateoftheartsoftware.com\/docs\/technical-documents\/file-format-user-defined-modbus-devices\/","title":{"rendered":"File Format: User Defined MODBUS Devices"},"content":{"rendered":"<style>\n.techdoc h3 {\n\tmargin-bottom:0;\n\tcolor:#27a;\n\ttext-align:left;\n}\n<\/style>\n<div class=\"techdoc\">\n<h3><u>History<\/u><\/h3>\n<p>When Eco Warrior Classic was first launched each type of device it was required to communicate with needed programming from scratch, which was a time consuming process.\u00a0 With Eco Warrior Pro the procedure of adding new devices was simplified by creating a set of building blocks (objects) which could be extended to work with new devices.\u00a0 For example there is a basic Modbus object which can be extended to support both RS485 and IP addressable modbus devices.\u00a0 The reduced the time and effort needed to support new types of device but still meant that some programming and a new version of Eco Warrior Pro was required each time a new logger or meter was added to the list of supported devices.<\/p>\n<p>As Modbus has (so far at least) been the most popular protocol for the devices we have been asked to support it was decided to create a custom&#8221;, or &#8220;user defined&#8221; device which could be programmed from a simple (well, reasonably simple!) text file.\u00a0 The result is described below.<\/p>\n<h3><u>Definition<\/u><\/h3>\n<p>These files are based on INI files.\u00a0 Whenever Eco Warrior Pro is run it scans the config folder (..EW32Config) for files ending with &#8220;.modbus&#8221; and attempts to load the definition, which it then adds to the list of possible devices.\u00a0 <strong>This means that once you have added a &#8220;custom&#8221; device using one of these files you MUST leave the .modbus file in the config folder or an error will occur when EWPro attempts to initialise the device.<\/strong><\/p>\n<p>For example, the file which defines an Autometer IC970 looks like this :-<\/p>\n<pre id=\"mycode\" style=\"margin-left: 72px;\"><span style=\"font-size: 14px;\"><span style=\"color: #ff0000;\"><strong>[Device]<\/strong><\/span>\r\n<strong>Name<\/strong>=Autometer IC970\r\n<strong>CircuitCount<\/strong>=9\r\n<strong>EnergyType<\/strong>=etElectric\r\n<strong>Comms<\/strong>=RS485\r\n<span style=\"color: #ff0000;\"><strong>[Group Start Registers]<\/strong><\/span>\r\n<strong>Group1<\/strong>=352\r\n<strong>Group2<\/strong>=80\r\n<strong>Group3<\/strong>=88\r\n<strong>Group4<\/strong>=16\r\n<strong>Group5<\/strong>=78\r\n<span style=\"color: #ff0000;\"><strong>[Item 1]<\/strong><\/span>\r\n<strong>Count<\/strong>=1\r\n<strong>Group<\/strong>=1\r\n<strong>Command<\/strong>=4\r\n<strong>LogMethod<\/strong>=Incremental\r\n<strong>EnergyUnit<\/strong>=eukW\r\n<strong>Caption<\/strong>=Active Energy Sum\r\n<strong>RegisterFormat<\/strong>=F32\r\n<span style=\"color: #ff0000;\"><strong>[Item 2]<\/strong><\/span>\r\n<strong>Count<\/strong>=3\r\n<strong>Group<\/strong>=2\r\n<strong>Command<\/strong>=4\r\n<strong>LogMethod<\/strong>=Variable(avg)\r\n<strong>EnergyUnit<\/strong>=euAmps\r\n<strong>Caption<\/strong>=Current Phase\r\n<strong>RegisterFormat<\/strong>=F32\r\n<span style=\"color: #ff0000;\"><strong>[Item 3]<\/strong><\/span>\r\n<strong>Count<\/strong>=1\r\n<strong>Group<\/strong>=3\r\n<strong>Command<\/strong>=4\r\n<strong>LogMethod<\/strong>=Variable(avg)\r\n<strong>EnergyUnit<\/strong>=euAmps\r\n<strong>Caption<\/strong>=Current Sum\r\n<strong>RegisterFormat<\/strong>=F32\r\n<span style=\"color: #ff0000;\"><strong>[Item 4]<\/strong><\/span>\r\n<strong>Count<\/strong>=3\r\n<strong>Group<\/strong>=4\r\n<strong>Command<\/strong>=4\r\n<strong>LogMethod<\/strong>=Variable(avg)\r\n<strong>EnergyUnit<\/strong>=euVolts\r\n<strong>Caption<\/strong>=Phase-Neutral Voltage Phase\r\n<strong>RegisterFormat<\/strong>=F32\r\n<span style=\"color: #ff0000;\"><strong>[Item 5]<\/strong><\/span>\r\n<strong>Count<\/strong>=1\r\n<strong>Group<\/strong>=5\r\n<strong>Command<\/strong>=4\r\n<strong>LogMethod<\/strong>=Variable(avg)\r\n<strong>EnergyUnit<\/strong>=euFrequency\r\n<strong>Caption<\/strong>=Frequency\r\n<strong>RegisterFormat<\/strong>=F32\r\n<\/span><\/pre>\n<p>The definition is split into sections.\u00a0 Each section begins with the name of the section in square brackets (eg &#8220;[Device]&#8221;).\u00a0 The section ends when a new section begins or when the end of the file is reached.<\/p>\n<p>The minimum number of sections is three, as there must be a &#8220;Device&#8221; section followed by a &#8220;Group Start Registers&#8221; section and at least one &#8220;Item&#8221; section.<\/p>\n<h3><u>Section: Device<\/u><\/h3>\n<p>These settings apply to the whole device and, in cases such as &#8220;EnergyType&#8221;, they apply to all circuits.<\/p>\n<table style=\"width: 100%;\">\n<tbody>\n<tr>\n<td><strong>Name<\/strong><\/td>\n<td><strong>Required<\/strong><\/td>\n<td>This is the device type as seen in EWPro<\/td>\n<\/tr>\n<tr>\n<td><strong>CircuitCount<\/strong><\/td>\n<td><strong>Required<\/strong><\/td>\n<td>MUST be equal to the number of circuits defined by all the &#8220;groups&#8221; in total (used as a cross-check)<\/td>\n<\/tr>\n<tr>\n<td><strong>EnergyType<\/strong><\/td>\n<td><strong>Required<\/strong><\/td>\n<td>The default energy type measured by this device as found in the Measurand File (&#8220;Internal Name&#8221;).<\/p>\n<p>The energy type can also be overridden for each item if required.<\/td>\n<\/tr>\n<tr>\n<td><strong>Comms<\/strong><\/td>\n<td><strong>Required<\/strong><\/td>\n<td>Defines the communications methods supported by the device. Options are &#8220;RS485&#8221; and &#8220;Network&#8221;.<\/p>\n<p>eg: &#8220;Comms=RS485,Network&#8221; OR &#8220;Comms=RS485&#8221; OR &#8220;Comms=Network&#8221;<\/td>\n<\/tr>\n<tr>\n<td>WordByteOrder<\/td>\n<td>Optional<\/td>\n<td>Defines the order of the Words within a Double-Word and the order of Bytes within each Word.<\/p>\n<p>Used when sending\/receiving packets of data to\/from the device.<\/p>\n<p>Options are :-<\/p>\n<p>&#8220;HH&#8221; \u2013 High byte first, High word first <em>(the default if no order is specified)<\/em><\/p>\n<p>&#8220;HL&#8221; \u2013 High byte first, Low word first<\/p>\n<p>&#8220;LH&#8221; \u2013 Low byte first, High word first<\/p>\n<p>&#8220;LL&#8221; \u2013 Low byte first , Low word first<\/p>\n<p>eg: &#8220;WordByteOrder=HL&#8221; (as used by EM21 meter)<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<h3><u>Section: Group Start Registers<\/u><\/h3>\n<p>Circuits can be clumped together in groups, to simplify and speed up communication.\u00a0 The fewer the number of groups that need to be read from a device, the fewer the number of packets of data which need requesting\/receiving and hence the sooner the communications process can be completed and we can move on to the next device.\u00a0 Each group of data starts at a given memory address within the device and continues sequentially for the remainder of the group.\u00a0 If a jump forwards or backwards in memory is needed then another group is required.<\/p>\n<table border=\"1\" width=\"100%\">\n<tbody>\n<tr>\n<td><strong>Group1<\/strong><\/td>\n<td><strong>Required<\/strong><\/td>\n<td>Specifies the starting address of the first register to read for the first &#8220;Group&#8221;<\/td>\n<\/tr>\n<tr>\n<td><strong>Group2<\/strong><\/td>\n<td>Optional<\/td>\n<td>Starting address for second group<\/td>\n<\/tr>\n<tr>\n<td><strong>Group<\/strong>&#8230;.<\/td>\n<td>Optional<\/td>\n<td>&#8230; and so on.\u00a0 There is no enforced limit to the number of groups.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<h3><u>Section: Item<\/u><\/h3>\n<p>A group is comprised of one or more &#8220;Items&#8221;.\u00a0 Each item comprises one or more registers, which must be situated sequentially in the memory of the device.\u00a0 You need to specify how many registers need reading, what size and type each register is, how they should be interpreted, which energy unit they are and to which group they belong.\u00a0 Each register in this &#8220;Item&#8221; must have the same settings.<\/p>\n<table style=\"width: 100%;\" border=\"1\">\n<tbody>\n<tr>\n<td><strong>Count<\/strong><\/td>\n<td><strong>Required<\/strong><\/td>\n<td>Number of sequential registers to read<\/td>\n<\/tr>\n<tr>\n<td><strong>Group<\/strong><\/td>\n<td><strong>Required<\/strong><\/td>\n<td>Which group this item belongs to<\/td>\n<\/tr>\n<tr>\n<td><strong>LogMethod<\/strong><\/td>\n<td><strong>Required<\/strong><\/td>\n<td>Options are :-<\/p>\n<p>&#8220;Incremental&#8221;,&#8221;Variable(min)&#8221;,&#8221;Variable(avg)&#8221;,&#8221;Variable(max)&#8221;,&#8221;Variable(ovr)&#8221;,<\/p>\n<p>&#8220;Variable(min\/max)&#8221;,&#8221;Variable(min\/avg\/max)&#8221;, etc, etc<\/p>\n<p>&#8230; for Minimum, Average, Maximum, Overwrite (always equal to last value)<\/p>\n<p>A circuit will be created for each variable type included.<\/td>\n<\/tr>\n<tr>\n<td>EnergyType<\/td>\n<td>Optional<\/td>\n<td>The energy type measured by this item, if different from the default value (see Device section).<\/p>\n<p>Valid values are found in the Measurand File (&#8220;Internal Name&#8221;).<\/td>\n<\/tr>\n<tr>\n<td><strong>EnergyUnit<\/strong><\/td>\n<td><strong>Required<\/strong><\/td>\n<td>The energy unit measured by each register as found in the Measurand File (see unit &#8220;Internal Name&#8221;)<\/td>\n<\/tr>\n<tr>\n<td><strong>Caption<\/strong><\/td>\n<td><strong>Required<\/strong><\/td>\n<td>This will be used as the basis for the circuit names.<\/p>\n<p>For example, if the caption is &#8220;Pulse&#8221;, the count is &#8220;2&#8221; and the LogMethod is &#8220;Incremental&#8221; then the circuit names will be &#8220;Pulse 1&#8221; and &#8220;Pulse 2&#8221;.<\/td>\n<\/tr>\n<tr>\n<td><strong>RegisterFormat<\/strong><\/td>\n<td><strong>Required<\/strong><\/td>\n<td>Options are :-<\/p>\n<p>&#8220;U16&#8221; &#8211; Unsigned Word<\/p>\n<p>&#8220;S16&#8221; &#8211; Signed 16-bit Integer<\/p>\n<p>&#8220;U32&#8221; &#8211; Unsigned Double-Word<\/p>\n<p>&#8220;S32&#8221; &#8211; Signed 32-bit Integer<\/p>\n<p>&#8220;U64&#8221; &#8211; Unsigned Quadword<\/p>\n<p>&#8220;S64&#8221; &#8211; Signed 64-bit Integer<\/p>\n<p>&#8220;F32&#8221; &#8211; 32-bit single-precision floating point (not an official mobus type but sometimes used)<\/td>\n<\/tr>\n<tr>\n<td>Command<\/td>\n<td>Optional<\/td>\n<td>The modbus command used to read the register(s).<\/p>\n<p>Default value is &#8220;3&#8221; if not specified.<\/p>\n<p>Some registers require command 4 &#8211; eg &#8220;Command=4&#8221;.<\/td>\n<\/tr>\n<tr>\n<td>ScalingFactor<\/td>\n<td>Optional<\/td>\n<td>Scaling to be applied to register value in order to convert to given unit type.<\/p>\n<p>Default is 1.0 if not specified.<\/p>\n<p>This is separate to the scaling factor which can be applied to each circuit in the Eco Warrior Pro configuration section.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<p>&nbsp;\n<\/p><\/div>\n","protected":false},"excerpt":{"rendered":"<p>History When Eco Warrior Classic was first launched each type of device it was required to communicate with needed programming from scratch, which was a time consuming process.\u00a0 With Eco Warrior Pro the procedure of adding new devices was simplified by creating a set of building blocks (objects) which could be extended to work with new devices.\u00a0 For example there<\/p>\n","protected":false},"author":1,"featured_media":0,"parent":19,"menu_order":10,"comment_status":"closed","ping_status":"closed","template":"","meta":{"footnotes":""},"_links":{"self":[{"href":"https:\/\/stateoftheartsoftware.com\/docs\/wp-json\/wp\/v2\/pages\/21"}],"collection":[{"href":"https:\/\/stateoftheartsoftware.com\/docs\/wp-json\/wp\/v2\/pages"}],"about":[{"href":"https:\/\/stateoftheartsoftware.com\/docs\/wp-json\/wp\/v2\/types\/page"}],"author":[{"embeddable":true,"href":"https:\/\/stateoftheartsoftware.com\/docs\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/stateoftheartsoftware.com\/docs\/wp-json\/wp\/v2\/comments?post=21"}],"version-history":[{"count":17,"href":"https:\/\/stateoftheartsoftware.com\/docs\/wp-json\/wp\/v2\/pages\/21\/revisions"}],"predecessor-version":[{"id":56,"href":"https:\/\/stateoftheartsoftware.com\/docs\/wp-json\/wp\/v2\/pages\/21\/revisions\/56"}],"up":[{"embeddable":true,"href":"https:\/\/stateoftheartsoftware.com\/docs\/wp-json\/wp\/v2\/pages\/19"}],"wp:attachment":[{"href":"https:\/\/stateoftheartsoftware.com\/docs\/wp-json\/wp\/v2\/media?parent=21"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}