esrf

Beamline Instrument Software Support
SPEC Macro documentation: [ Macro Index | BCU Home ]

MODBUS.MAC
See other macros in category: Generic I/O
Description:
    Macro functions to access slave MODBUS or MODBUS/TCP devices.
Documentation:
    DESCRIPTION
    This macro set provides functions to access remote devices using MODBUS protocol over serial lines or MODBUS/TCP over TCP/IP.

    The following MODBUS functions are implemented:
      • FC1: Read Coils
      • FC2: Read Input Discretes
      • FC3: Read Multiple Registers
      • FC4: Read Input Registers
      • FC5: Write Coil
      • FC6: Write Single Register
      • FC7: Read Exception Status
      • FC11: Get Comm Event Counters
      • FC15: Force Multiple Coils
      • FC16: Write Multiple Registers
    The remote devices must behave as MODBUS slave nodes and have to be register with the modb_addnode() macro function before being accessed. This function returns a node number that must be used as the first parameter of the all the macro functions used to exchange data with the remote devices.
    Many of the input/output functions use an array to transfer data. This array can be a data array or an associative array. In the case of using a data array, the user is responsible of providing an array of the correct size to hold the data.

    When an error happens during the execution of a MODBUS function or an exception is received from a slave node, the corresponding error or exception code is stored in the global variable MODB_ERR if it exists and the macro function returns the negative value -MODB_ERR. An error message is printed on the output terminal unless MODB_ERR is previously set to -1. If the function completes succesfully, MODB_ERR is set to 0.

    The error codes are the following:
      • 1001 - Bad device or interface
      • 1002 - Bad address
      • 1003 - Bad data parameters
      • 1004 - Not a registered slave node
      • 1005 - No answer from slave node
      • 1006 - Bad answer from slave node
      • 1007 - Function mismatch
    The most frequent MODBUS exception codes are:
      • 1 - Illegal Function
      • 2 - Illegal Data Address
      • 3 - Illegal Data Value


    EXAMPLE
    myslave = modb_addnode(3, 47)
    modb_write_reg(myslave, 0x100, 0xFFFF)
    This writes the value 0xFFFF in the register 0x100 of the slave with MODBUS address 47 that is connected to the spec serial interface 3.
    modb_addnode("id33wagoeh2")
    This macro checks the connection with the MODBUS/TCP slave id33wagoeh2 and adds it to the internal node list.

    INTERNALS
    ???.

Macros:
    modb_addnode
    Usage: modb_addnode (<device>, <maddr> [, <name> [, <flags>]])
    Tries to connect to a MODBUS slave node. If the node is found, the macro function appends it to the internal list and returns a unique node number that must be used to access the slave with this macro set.
    In the case of slave nodes interfaced by serial line connection, the parameter <device> must be either the number of a serial line interface or an ESRF device name. The parameter <maddr> is required and must correspond to the MODBUS address of the node.
    In the case of a MODBUS/TCP connection, <device> must be the network name or IP address of the slave node and the address <maddr> may be meaningless, as it is usually ignored by the slave.
    If there is an error, the macro returns -MODB_ERR, and the node is not added to the internal list.


    modbshow
    Usage: modbshow
    Displays the list of the current defined MODBUS nodes.


    modb_read_coils
    Usage: modb_read_coils (<node>, <daddr>, <ncoils>, <data>)
    This macro executes the function FC1:Read Coils in a slave MODBUS node. The slave node is selected by the parameter <node> that must be a valid value previously returned by the macro function modb_addnode(). The parameters <daddr> and <ncoils> contain the address of the first bit (coil) and the total number of bits (coils) to read.
    If no error happens, the macro function returns the number of bits actually read from the slave and stored in the first positions of the array <data>. Each valid position of <data> contains one bit with a value of 0 or 1. If an error happens, the macro returns -MODB_ERR (see error codes).


    modb_read_inputs
    Usage: modb_read_inputs (<node>, <daddr>, <ninp>, <data>)
    This macro executes the function FC2:Read Input Discretes in a slave MODBUS node. The slave node is selected by the parameter <node> that must be a valid value previously returned by the macro function modb_addnode(). The parameters <daddr> and <ninp> contain the address of first input bit and the total number of bits to read.
    If no error happens, the macro function returns the number of bits actually read from the slave and stored in the first positions of the array <data>. Each valid position of <data> contains one bit with a value of 0 or 1. If an error happens, the macro returns -MODB_ERR (see error codes).


    modb_read_multregs
    Usage: modb_read_multregs (<node>, <daddr>, <nreg>, <data>)
    This macro executes the function FC3:Read Multiple Registers in a slave MODBUS node. The slave node is selected by the parameter <node> that must be a valid value previously returned by the macro function modb_addnode(). The parameters <daddr> and <nreg> contain the address of first input register (word) and the total number of registers (words) to read.
    If no error happens, the macro function returns the number of words actually read from the slave and stored in the first positions of the array <data>. Each valid position of <data> contains a 16-bit word. If an error happens, the macro returns -MODB_ERR (see error codes).


    modb_read_inpregs
    Usage: modb_read_inpregs (<node>, <daddr>, <nreg>, <data>)
    This macro executes the function FC4:Read Input Registers in a slave MODBUS node. The slave node is selected by the parameter <node> that must be a valid value previously returned by the macro function modb_addnode(). The parameters <daddr> and <nreg> contain the address of first input register (word) and the total number of registers (words) to read.
    If no error happens, the macro function returns the number of words actually read from the slave and stored in the first positions of the array <data>. Each valid position of <data> contains a 16-bit word. If an error happens, the macro returns -MODB_ERR (see error codes).


    modb_write_coil
    Usage: modb_write_coil (<node>, <daddr>, <value>)
    This macro executes the function FC5:Write Coil in a slave MODBUS node. The slave node is selected by the parameter <node> that must be a valid value previously returned by the macro function modb_addnode(). The parameter <daddr> contains the address of the bit (coil) to access and <value> contains the logical value (0 or 1) to write.
    If an error happens, the macro returns -MODB_ERR (see error codes), otherwise 0.


    modb_write_reg
    Usage: modb_write_reg (<node>, <daddr>, <value>)
    This macro executes the function FC6:Write Single Register in a slave MODBUS node. The slave node is selected by the parameter <node> that must be a valid value previously returned by the macro function modb_addnode(). The parameter <daddr> contains the address of the word (register) to access and <value> contains the 16-bit value.
    If an error happens, the macro returns -MODB_ERR (see error codes), otherwise 0.


    modb_read_status
    Usage: modb_read_status (<node>, <data>)
    This macro executes the function FC7:Read Exception Status in a slave MODBUS node. The slave node is selected by the parameter <node> that must be a valid value previously returned by the macro function modb_addnode(). The 8-bit status is returned in the first element of the array <data>.
    If an error happens, the macro returns -MODB_ERR (see error codes), otherwise 1.


    modb_get_eventcnt
    Usage: modb_get_eventcnt (<node>, <data>)
    This macro executes the function FC11:Get Comm Event Counter in a slave MODBUS node. The slave node is selected by the parameter <node> that must be a valid value previously returned by the macro function modb_addnode(). If no error happens, the node status word and the event count are stored in the first two positions of the array <data> and the macro function returns 2. If an error happens, the macro returns -MODB_ERR (see error codes).


    modb_force_coils
    Usage: modb_force_coils (<node>, <daddr>, <ncoils>, <data>)
    This macro executes the function FC15:Force Multiple Coils in a slave MODBUS node. The slave node is selected by the parameter <node> that must be a valid value previously returned by the macro function modb_addnode(). The parameters <daddr> and <ncoils> contain the address of first bit (coil) and the total number of bits (coils) to write. The first positions of the array <data> cointain the logical values to write. Each valid position of <data> must contain only one bit with a value of 0 or 1.
    If an error happens, the macro returns -MODB_ERR (see error codes), otherwise 0.


    modb_write_regs
    Usage: modb_write_regs (<node>, <daddr>, <nregs>, <data>)
    This macro executes the function FC16:Write Multiple Registers in a slave MODBUS node. The slave node is selected by the parameter <node> that must be a valid value previously returned by the macro function modb_addnode(). The parameters <daddr> and <nregs> contain the address of first word (register) and the total number of words (registers) to write. The first positions of the array <data> cointain the register values to write. Each valid position of <data> must contain a 16-bit word.
    If an error happens, the macro returns -MODB_ERR (see error codes), otherwise 0.


    modbdebug
    Usage: modbdebug


Internal Macros:
    modb_ipcheck
    Usage: modb_ipcheck(device)


    get_subnet
    Usage: get_subnet(computer)


    modb_is_tcp
    Usage: modb_is_tcp(device)


    modb__read
    Usage: modb__read (<node>, <daddr>, <nitems>, <data>, <function>)
    Executes any read data function in a slave MODBUS node.


    modb__data
    Usage: modb__data (<data>, <nitems>)
    Extracts <nitems> data from the binary frame in MODBFRAME and stores them in the array <data>.


    modb__checkpar
    Usage: modb__checkpar (<nitems>, <data>)
    Checks that nitems is in the (1, 0xFFFF) range and that data is an array of the right capacity.


    modb__frame
    Usage: modb__frame (<node>, <funct>, <word1>, <word2>, <data>)
    Builds a modbus frame from the input parameters <funct>, <word1>, <word2> and <data>. The frame is stored in the global byte array MODBFRAME[] starting from the position 1.


    modb__put
    Usage: modb__put (<node>)
    Sends a message to a slave node and gets the answer back. The message is constructed from a valid modbus frame previously stored in the byte array MODBFRAME[]. The answer from the slave is stored also in MODBFRAME[], overwritting the initial content. The return value is the length of the answer frame or -MODB_ERR in case of error.


    modb__get
    Usage: modb__get(node, funct)


    modb__get
    Usage: modb__get(node, funct)


    modb__getlow
    Usage: modb__getlow(node)


    __modb__getdata
    Usage: __modb__getdata(node, funct)


    modb__buildstr
    Usage: modb__buildstr ()
    Returns an ASCII MODBUS message string build from a modbus frame previously stored in the byte array MODBFRAME[]. The string includes the LRC bytes and all the required control characters.


    modb__chkstr
    Usage: modb__chkstr (<str>)
    Converts an ASCII MODBUS answer in <str> into a byte binary sequence that is stored in MODBFRAME[].
    If the macro detects a MODBUS exception or a LRC error returns -MODB_ERR, otherwise returns the length of the answer frame.


    modb__chkanswer
    Usage: modb__chkanswer ()
    Checks the received frame for a MODBUS exception and returns the error code. If no exception, it returns the length of the answer frame.


    modb__debug_start
    Usage: modb__debug_start


    modb__debug
    Usage: modb__debug


Filename: modbus.mac
Author: P. Fajardo, (Original 5/01). $Revision: 1.2 $ / $Date: 2008/08/12 13:59:19 $
Last mod.: 12/08/2008 15:59 by rey