| /* |
| * Copyright (c) 2020 PHYTEC Messtechnik GmbH |
| * Copyright (c) 2021 Nordic Semiconductor ASA |
| * |
| * SPDX-License-Identifier: Apache-2.0 |
| */ |
| |
| /* |
| * Client API in this file is based on mbm_core.c from uC/Modbus Stack. |
| * |
| * uC/Modbus |
| * The Embedded Modbus Stack |
| * |
| * Copyright 2003-2020 Silicon Laboratories Inc. www.silabs.com |
| * |
| * SPDX-License-Identifier: APACHE-2.0 |
| * |
| * This software is subject to an open source license and is distributed by |
| * Silicon Laboratories Inc. pursuant to the terms of the Apache License, |
| * Version 2.0 available at www.apache.org/licenses/LICENSE-2.0. |
| */ |
| |
| /** |
| * @brief MODBUS transport protocol API |
| * @defgroup modbus MODBUS |
| * @ingroup io_interfaces |
| * @{ |
| */ |
| |
| #ifndef ZEPHYR_INCLUDE_MODBUS_H_ |
| #define ZEPHYR_INCLUDE_MODBUS_H_ |
| |
| #include <drivers/uart.h> |
| |
| #ifdef __cplusplus |
| extern "C" { |
| #endif |
| |
| /** Length of MBAP Header */ |
| #define MODBUS_MBAP_LENGTH 7 |
| /** Length of MBAP Header plus function code */ |
| #define MODBUS_MBAP_AND_FC_LENGTH (MODBUS_MBAP_LENGTH + 1) |
| |
| /** |
| * @brief Frame struct used internally and for raw ADU support. |
| */ |
| struct modbus_adu { |
| /** Transaction Identifier */ |
| uint16_t trans_id; |
| /** Protocol Identifier */ |
| uint16_t proto_id; |
| /** Length of the data only (not the length of unit ID + PDU) */ |
| uint16_t length; |
| /** Unit Identifier */ |
| uint8_t unit_id; |
| /** Function Code */ |
| uint8_t fc; |
| /** Transaction Data */ |
| uint8_t data[CONFIG_MODBUS_BUFFER_SIZE - 4]; |
| /** RTU CRC */ |
| uint16_t crc; |
| }; |
| |
| /** |
| * @brief Coil read (FC01) |
| * |
| * Sends a Modbus message to read the status of coils from a server. |
| * |
| * @param iface Modbus interface index |
| * @param unit_id Modbus unit ID of the server |
| * @param start_addr Coil starting address |
| * @param coil_tbl Pointer to an array of bytes containing the value |
| * of the coils read. |
| * The format is: |
| * |
| * MSB LSB |
| * B7 B6 B5 B4 B3 B2 B1 B0 |
| * ------------------------------------- |
| * coil_tbl[0] #8 #7 #1 |
| * coil_tbl[1] #16 #15 #9 |
| * : |
| * : |
| * |
| * Note that the array that will be receiving the coil |
| * values must be greater than or equal to: |
| * (num_coils - 1) / 8 + 1 |
| * @param num_coils Quantity of coils to read |
| * |
| * @retval 0 If the function was successful |
| */ |
| int modbus_read_coils(const int iface, |
| const uint8_t unit_id, |
| const uint16_t start_addr, |
| uint8_t *const coil_tbl, |
| const uint16_t num_coils); |
| |
| /** |
| * @brief Read discrete inputs (FC02) |
| * |
| * Sends a Modbus message to read the status of discrete inputs from |
| * a server. |
| * |
| * @param iface Modbus interface index |
| * @param unit_id Modbus unit ID of the server |
| * @param start_addr Discrete input starting address |
| * @param di_tbl Pointer to an array that will receive the state |
| * of the discrete inputs. |
| * The format of the array is as follows: |
| * |
| * MSB LSB |
| * B7 B6 B5 B4 B3 B2 B1 B0 |
| * ------------------------------------- |
| * di_tbl[0] #8 #7 #1 |
| * di_tbl[1] #16 #15 #9 |
| * : |
| * : |
| * |
| * Note that the array that will be receiving the discrete |
| * input values must be greater than or equal to: |
| * (num_di - 1) / 8 + 1 |
| * @param num_di Quantity of discrete inputs to read |
| * |
| * @retval 0 If the function was successful |
| */ |
| int modbus_read_dinputs(const int iface, |
| const uint8_t unit_id, |
| const uint16_t start_addr, |
| uint8_t *const di_tbl, |
| const uint16_t num_di); |
| |
| /** |
| * @brief Read holding registers (FC03) |
| * |
| * Sends a Modbus message to read the value of holding registers |
| * from a server. |
| * |
| * @param iface Modbus interface index |
| * @param unit_id Modbus unit ID of the server |
| * @param start_addr Register starting address |
| * @param reg_buf Is a pointer to an array that will receive |
| * the current values of the holding registers from |
| * the server. The array pointed to by 'reg_buf' needs |
| * to be able to hold at least 'num_regs' entries. |
| * @param num_regs Quantity of registers to read |
| * |
| * @retval 0 If the function was successful |
| */ |
| int modbus_read_holding_regs(const int iface, |
| const uint8_t unit_id, |
| const uint16_t start_addr, |
| uint16_t *const reg_buf, |
| const uint16_t num_regs); |
| |
| /** |
| * @brief Read input registers (FC04) |
| * |
| * Sends a Modbus message to read the value of input registers from |
| * a server. |
| * |
| * @param iface Modbus interface index |
| * @param unit_id Modbus unit ID of the server |
| * @param start_addr Register starting address |
| * @param reg_buf Is a pointer to an array that will receive |
| * the current value of the holding registers |
| * from the server. The array pointed to by 'reg_buf' |
| * needs to be able to hold at least 'num_regs' entries. |
| * @param num_regs Quantity of registers to read |
| * |
| * @retval 0 If the function was successful |
| */ |
| int modbus_read_input_regs(const int iface, |
| const uint8_t unit_id, |
| const uint16_t start_addr, |
| uint16_t *const reg_buf, |
| const uint16_t num_regs); |
| |
| /** |
| * @brief Write single coil (FC05) |
| * |
| * Sends a Modbus message to write the value of single coil to a server. |
| * |
| * @param iface Modbus interface index |
| * @param unit_id Modbus unit ID of the server |
| * @param coil_addr Coils starting address |
| * @param coil_state Is the desired state of the coil |
| * |
| * @retval 0 If the function was successful |
| */ |
| int modbus_write_coil(const int iface, |
| const uint8_t unit_id, |
| const uint16_t coil_addr, |
| const bool coil_state); |
| |
| /** |
| * @brief Write single holding register (FC06) |
| * |
| * Sends a Modbus message to write the value of single holding register |
| * to a server unit. |
| * |
| * @param iface Modbus interface index |
| * @param unit_id Modbus unit ID of the server |
| * @param start_addr Coils starting address |
| * @param reg_val Desired value of the holding register |
| * |
| * @retval 0 If the function was successful |
| */ |
| int modbus_write_holding_reg(const int iface, |
| const uint8_t unit_id, |
| const uint16_t start_addr, |
| const uint16_t reg_val); |
| |
| /** |
| * @brief Read diagnostic (FC08) |
| * |
| * Sends a Modbus message to perform a diagnostic function of a server unit. |
| * |
| * @param iface Modbus interface index |
| * @param unit_id Modbus unit ID of the server |
| * @param sfunc Diagnostic sub-function code |
| * @param data Sub-function data |
| * @param data_out Pointer to the data value |
| * |
| * @retval 0 If the function was successful |
| */ |
| int modbus_request_diagnostic(const int iface, |
| const uint8_t unit_id, |
| const uint16_t sfunc, |
| const uint16_t data, |
| uint16_t *const data_out); |
| |
| /** |
| * @brief Write coils (FC15) |
| * |
| * Sends a Modbus message to write to coils on a server unit. |
| * |
| * @param iface Modbus interface index |
| * @param unit_id Modbus unit ID of the server |
| * @param start_addr Coils starting address |
| * @param coil_tbl Pointer to an array of bytes containing the value |
| * of the coils to write. |
| * The format is: |
| * |
| * MSB LSB |
| * B7 B6 B5 B4 B3 B2 B1 B0 |
| * ------------------------------------- |
| * coil_tbl[0] #8 #7 #1 |
| * coil_tbl[1] #16 #15 #9 |
| * : |
| * : |
| * |
| * Note that the array that will be receiving the coil |
| * values must be greater than or equal to: |
| * (num_coils - 1) / 8 + 1 |
| * @param num_coils Quantity of coils to write |
| * |
| * @retval 0 If the function was successful |
| */ |
| int modbus_write_coils(const int iface, |
| const uint8_t unit_id, |
| const uint16_t start_addr, |
| uint8_t *const coil_tbl, |
| const uint16_t num_coils); |
| |
| /** |
| * @brief Write holding registers (FC16) |
| * |
| * Sends a Modbus message to write to integer holding registers |
| * to a server unit. |
| * |
| * @param iface Modbus interface index |
| * @param unit_id Modbus unit ID of the server |
| * @param start_addr Register starting address |
| * @param reg_buf Is a pointer to an array containing |
| * the value of the holding registers to write. |
| * Note that the array containing the register values must |
| * be greater than or equal to 'num_regs' |
| * @param num_regs Quantity of registers to write |
| * |
| * @retval 0 If the function was successful |
| */ |
| int modbus_write_holding_regs(const int iface, |
| const uint8_t unit_id, |
| const uint16_t start_addr, |
| uint16_t *const reg_buf, |
| const uint16_t num_regs); |
| |
| /** |
| * @brief Read floating-point holding registers (FC03) |
| * |
| * Sends a Modbus message to read the value of floating-point |
| * holding registers from a server unit. |
| * |
| * @param iface Modbus interface index |
| * @param unit_id Modbus unit ID of the server |
| * @param start_addr Register starting address |
| * @param reg_buf Is a pointer to an array that will receive |
| * the current values of the holding registers from |
| * the server. The array pointed to by 'reg_buf' needs |
| * to be able to hold at least 'num_regs' entries. |
| * @param num_regs Quantity of registers to read |
| * |
| * @retval 0 If the function was successful |
| */ |
| int modbus_read_holding_regs_fp(const int iface, |
| const uint8_t unit_id, |
| const uint16_t start_addr, |
| float *const reg_buf, |
| const uint16_t num_regs); |
| |
| /** |
| * @brief Write floating-point holding registers (FC16) |
| * |
| * Sends a Modbus message to write to floating-point holding registers |
| * to a server unit. |
| * |
| * @param iface Modbus interface index |
| * @param unit_id Modbus unit ID of the server |
| * @param start_addr Register starting address |
| * @param reg_buf Is a pointer to an array containing |
| * the value of the holding registers to write. |
| * Note that the array containing the register values must |
| * be greater than or equal to 'num_regs' |
| * @param num_regs Quantity of registers to write |
| * |
| * @retval 0 If the function was successful |
| */ |
| int modbus_write_holding_regs_fp(const int iface, |
| const uint8_t unit_id, |
| const uint16_t start_addr, |
| float *const reg_buf, |
| const uint16_t num_regs); |
| |
| /** Modbus Server User Callback structure */ |
| struct modbus_user_callbacks { |
| /** Coil read callback */ |
| int (*coil_rd)(uint16_t addr, bool *state); |
| |
| /** Coil write callback */ |
| int (*coil_wr)(uint16_t addr, bool state); |
| |
| /** Discrete Input read callback */ |
| int (*discrete_input_rd)(uint16_t addr, bool *state); |
| |
| /** Input Register read callback */ |
| int (*input_reg_rd)(uint16_t addr, uint16_t *reg); |
| |
| /** Floating Point Input Register read callback */ |
| int (*input_reg_rd_fp)(uint16_t addr, float *reg); |
| |
| /** Holding Register read callback */ |
| int (*holding_reg_rd)(uint16_t addr, uint16_t *reg); |
| |
| /** Holding Register write callback */ |
| int (*holding_reg_wr)(uint16_t addr, uint16_t reg); |
| |
| /** Floating Point Holding Register read callback */ |
| int (*holding_reg_rd_fp)(uint16_t addr, float *reg); |
| |
| /** Floating Point Holding Register write callback */ |
| int (*holding_reg_wr_fp)(uint16_t addr, float reg); |
| }; |
| |
| /** |
| * @brief Get Modbus interface index according to interface name |
| * |
| * If there is more than one interface, it can be used to clearly |
| * identify interfaces in the application. |
| * |
| * @param iface_name Modbus interface name |
| * |
| * @retval Modbus interface index or negative error value. |
| */ |
| int modbus_iface_get_by_name(const char *iface_name); |
| |
| /** |
| * @brief ADU raw callback function signature |
| * |
| * @param iface Modbus RTU interface index |
| * @param adu Pointer to the RAW ADU struct to send |
| * |
| * @retval 0 If transfer was successful |
| */ |
| typedef int (*modbus_raw_cb_t)(const int iface, const struct modbus_adu *adu); |
| |
| /** |
| * @brief Modbus interface mode |
| */ |
| enum modbus_mode { |
| /** Modbus over serial line RTU mode */ |
| MODBUS_MODE_RTU, |
| /** Modbus over serial line ASCII mode */ |
| MODBUS_MODE_ASCII, |
| /** Modbus raw ADU mode */ |
| MODBUS_MODE_RAW, |
| }; |
| |
| /** |
| * @brief Modbus serial line parameter |
| */ |
| struct modbus_serial_param { |
| /** Baudrate of the serial line */ |
| uint32_t baud; |
| /** parity UART's parity setting: |
| * UART_CFG_PARITY_NONE, |
| * UART_CFG_PARITY_EVEN, |
| * UART_CFG_PARITY_ODD |
| */ |
| enum uart_config_parity parity; |
| }; |
| |
| /** |
| * @brief Modbus server parameter |
| */ |
| struct modbus_server_param { |
| /** Pointer to the User Callback structure */ |
| struct modbus_user_callbacks *user_cb; |
| /** Modbus unit ID of the server */ |
| uint8_t unit_id; |
| }; |
| |
| /** |
| * @brief User parameter structure to configure Modbus interfase |
| * as client or server. |
| */ |
| struct modbus_iface_param { |
| /** Mode of the interface */ |
| enum modbus_mode mode; |
| union { |
| struct modbus_server_param server; |
| /** Amount of time client will wait for |
| * a response from the server. |
| */ |
| uint32_t rx_timeout; |
| }; |
| union { |
| /** Serial support parameter of the interface */ |
| struct modbus_serial_param serial; |
| /** Pointer to raw ADU callback function */ |
| modbus_raw_cb_t raw_tx_cb; |
| }; |
| }; |
| |
| /** |
| * @brief Configure Modbus Interface as raw ADU server |
| * |
| * @param iface Modbus RTU interface index |
| * @param param Configuration parameter of the server interface |
| * |
| * @retval 0 If the function was successful |
| */ |
| int modbus_init_server(const int iface, struct modbus_iface_param param); |
| |
| /** |
| * @brief Configure Modbus Interface as raw ADU client |
| * |
| * @param iface Modbus RTU interface index |
| * @param param Configuration parameter of the client interface |
| * |
| * @retval 0 If the function was successful |
| */ |
| int modbus_init_client(const int iface, struct modbus_iface_param param); |
| |
| /** |
| * @brief Disable Modbus Interface |
| * |
| * This function is called to disable Modbus interface. |
| * |
| * @param iface Modbus interface index |
| * |
| * @retval 0 If the function was successful |
| */ |
| int modbus_disable(const uint8_t iface); |
| |
| /** |
| * @brief Submit raw ADU |
| * |
| * @param iface Modbus RTU interface index |
| * @param adu Pointer to the RAW ADU struct that is received |
| * |
| * @retval 0 If transfer was successful |
| */ |
| int modbus_raw_submit_rx(const int iface, const struct modbus_adu *adu); |
| |
| /** |
| * @brief Put MBAP header into a buffer |
| * |
| * @param adu Pointer to the RAW ADU struct |
| * @param header Pointer to the buffer in which MBAP header |
| * will be placed. |
| * |
| * @retval 0 If transfer was successful |
| */ |
| void modbus_raw_put_header(const struct modbus_adu *adu, uint8_t *header); |
| |
| /** |
| * @brief Get MBAP header from a buffer |
| * |
| * @param adu Pointer to the RAW ADU struct |
| * @param header Pointer to the buffer containing MBAP header |
| * |
| * @retval 0 If transfer was successful |
| */ |
| void modbus_raw_get_header(struct modbus_adu *adu, const uint8_t *header); |
| |
| /** |
| * @brief Set Server Device Failure exception |
| * |
| * This function modifies ADU passed by the pointer. |
| * |
| * @param adu Pointer to the RAW ADU struct |
| */ |
| void modbus_raw_set_server_failure(struct modbus_adu *adu); |
| |
| /** |
| * @brief Use interface as backend to send and receive ADU |
| * |
| * This function overwrites ADU passed by the pointer and generates |
| * exception responses if backend interface is misconfigured or |
| * target device is unreachable. |
| * |
| * @param iface Modbus client interface index |
| * @param adu Pointer to the RAW ADU struct |
| * |
| * @retval 0 If transfer was successful |
| */ |
| int modbus_raw_backend_txn(const int iface, struct modbus_adu *adu); |
| |
| #ifdef __cplusplus |
| } |
| #endif |
| |
| /** |
| * @} |
| */ |
| |
| #endif /* ZEPHYR_INCLUDE_MODBUS_H_ */ |
