Differences

This shows you the differences between two versions of the page.

--- custom_protocols [2019/01/09 12:35] – [The examples of custom protocols] emozolyak
+++ custom_protocols [2023/02/21 17:52] (current) – [writeRegister] emozolyak
@@ Line 1: / Line 1: @@
+{{ network:edti_protocol_icon.png?nolink&80}}
 ====== Custom protocols ======
-There are a lot of different automation devices with non-standard communication protocols. To solve the problem of data collection from such devices in WebHMI, it is possible to create custom protocols in [[ https://www.lua.org/ | Lua ]]. This function is available in WebHMI since version 1.10.0.3420.
+There are a lot of different automation devices with non-standard communication protocols. To solve the problem of data collection from such devices in WebHMI, it is possireble to create custom protocols in [[ https://www.lua.org/ | Lua ]]. This function is available in WebHMI since version 1.10.0.3420.
 ===== About Lua =====
@@ Line 21: / Line 22: @@
 To go to the list of user protocols, click on the button "Custom protocols" the Setup -> Registers -> Tools sub-menu.
-{{ ::add_custom_protocol.png?direct |}}
+{{ network:add_custom_protocol.png?direct&600 |}}
 You will be taken to the protocol management page. In this example, we see two demonstration protocols - ModBus TCP Demo and ModBus ASCII Demo:
-{{ ::custom_prot_list.png?direct&600 |}}
+{{ network:custom_prot_list.png?direct&400 |}}
 Let's look at the page for editing the ModBus TCP Demo protocol:
@@ Line 40: / Line 41: @@
 The regular expression must ensure that the register address is validated on the register editing page (when this protocol is selected). Example:
-{{ ::custom_prot_addr_valid.png?direct&912 |}}
+{{ network:custom_prot_addr_valid.png?direct&600 |}}
 We also see a convenient code editor. It supports formatting, highlighting and validation of syntax. So it's convenient to write the code
 If there is a syntax error in the code, a red X appears in the corresponding line. To see a detailed error message, just point your mouse at it:
-{{::custom_protocol_syntax_check.png?direct&912}}
+{{  network:custom_protocol_syntax_check.png?direct&600 }}
 After creating the protocol, it will appear in the drop-down list of available PLC models on the page of creating newConnections and with it you can work as well as with the usual built-in protocol:
-{{ :custom_protocol_list.png?direct |}}
+{{ network:custom_protocol_list.png?direct&600 |}}
 ===== Necessary functions =====
@@ Line 89: / Line 90: @@
 The function readRegister should read the specified register.
-In case of successful reading, the function readRegister should return an array of bytes, with length corresponding to the specified data type (1, 2 or 4) or the number. In case of failure, you must return false.
+In case of successful reading, the function readRegister should return an //(lua table)// **array of bytes, with length corresponding to the specified data type** (1, 2 or 4) or the number. In case of failure, you must return **boolean false**.
 Three parameters are passed to it as arguments:
-reg - Table (structure) with register parameters
+  ***reg** - Table (structure) with register parameters
-device - Table (structure) with register type parameters (that were defined in createDevices)
+  ***device** - Table (structure) with register type parameters (that were defined in createDevices)
-unitId – device ID for the bus or other ID. For instance, Slave ID in ModBus RTU or Unit ID in ModBus TCP.
+  ***unitId** – device ID for the bus or other ID. For instance, Slave ID in ModBus RTU or Unit ID in ModBus TCP.
-There are such attributes in the reg structure:
-internalAddr - Recalculated register address. This number is recalculated from the specified number system with shift added to it.
+=== Attributes of the REG structure ===
-addr - The original address of the register that the user entered.
-dataType – The type of data that the user specified for the register. 0 = Bit, 1 = Byte, 2 = Word, 3 = Double Word, 4 = UnixTime
-There are such attributes in the device structure:
-shift - The shift value from the corresponding row in createDevices
+  *internalAddr - Recalculated register address. This number is recalculated from the specified number system with shift added to it.
-base - base value from the corresponding row in createDevices
+  *addr - The original address of the register that the user entered.
-xtraFields – xtraFields value from the corresponing row in createDevices
+  *dataType – The type of data that the user specified for the register. 0 = Bit, 1 = Byte, 2 = Word, 3 = Double Word, 4 = UnixTime
+=== Attributes of the DEVICE structure ===
+  *shift - The shift value from the corresponding row in createDevices
+  *base - base value from the corresponding row in createDevices
+  *xtraFields – xtraFields value from the corresponing row in createDevices
 These parameters are passed in order to be able to correctly and fully compose a request according to the protocol.
-Для передачи запроса устройству используются функции sendBytes и sendString. Для чтения ответа - readBytes, readString.
+To send a request to the device //sendBytes// and //sendString// are used. To read the reply //readBytes// and //readString// respectively. Their overview is given in the following table:
+^ Function ^ Arguments ^ Returns ^
+|sendBytes  |table | true/false (success execution or no) |
+|sendString |string| same |
+|readBytes  |number (of bytes to read)| table of bytes or false for error |
+|readString |number (of chars to read)| string  or false for error |
-На вход sendBytes принимает таблицу (массив) байт. Результатом будет true в случае успеха и false в случае ошибки.
+To close connection (in case of many errors), //closeConnection// function can be used.
-На вход sendString принимает строку. Результатом будет true в случае успеха и false в случае ошибки.
-На вход readBytes принимает количество байт, которое необходимо прочитать. Результатом будет таблица (массив) байт в случае успеха и false в случае ошибки.
-На вход readString принимает количество байт, которое необходимо прочитать. Результатом будет строка в случае успеха и false в случае ошибки.
-Если необходимо закрыть соединение (например, в случае множественных ошибок), то можно вызвать процедуру closeConnection.
-Если необходимо сделать паузу, то можно вызвать функцию sleep. Ее единственным аргументом должно быть время в микросекундах. Пример: sleep(20000); - произойдет пауза 20 миллисекунд.
+To make a delay, //sleep// function can be used. Its only argument is time in microseconds, e.g. sleep(20000) will make a pause for 20 ms.
-Для работы с битами можно использовать библиотеку bitop [4].
+For bit processing refer to bitop library and this [[useful_programs#bit_functions | link]].
-Для отладки и вывода диагностических сообщений можно использовать процедуры ERROR, INFO, DEBUG и TRACE которые доступны и в обычных сценариях Lua [5].
+For debugging and diagnostic messages you can use ERROR, INFO, DEBUG or TRACE from the users Lua scripts - see [[write_to_logs | this]].
-Что бы лучше понять как это все работает давайте рассмотрим пример функции readRegister для протокола ModBus TCP:
+To better understand the custom protocol application, let's examine the readRegister function for the ModBus TCP protocol:
 <code lua>
@@ Line 259: / Line 264: @@
 The writeRegister function should write a new value to the specified register. If the record is successful, it should return true. In case of an error, false.
-Ей передаются все те же параметры, что и для readRegister, а также дополнительно четвертый параметр - новое значение. It has all the same arguments as for readRegister, as well as an additional fourth argument, a new value.
+It has the same arguments as the readRegister, as well as fourth parameter which is a new value.
 The writeRegister function may use the same methods of reading from and writing bytes to the port.
@@ Line 444: / Line 449: @@
 As an example we've made (partually) several protocols:
-  *[[http://docs.webhmi.com.ua/modbus_tcp_custom|ModBus TCP]]
+  *[[modbus_tcp_custom|ModBus TCP]]
-  *[[http://docs.webhmi.com.ua/modbus_ascii_custom|ModBus ASCII]]
+  *[[modbus_ascii_custom|ModBus ASCII]]
-  *[[http://docs.webhmi.com.ua/modbus_rtu_custom|Modbus RTU]].
+  *[[modbus_rtu_custom|Modbus RTU]].
+  *[[http_get_custom | HTTP request example]]
   *Other devices that were connected using [[http://docs.webhmi.com.ua/examples_of_webhmi_connections_to_various_devices|custom protocols]]