diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index 2fc4b09..9311446 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -5,8 +5,7 @@ stages: variables: # System environment - TARGET_TEST_ENV_IMAGE: "$CI_DOCKER_REGISTRY/target-test-env-v5.2:2" - ESP_DOCS_ENV_IMAGE: "$CI_DOCKER_REGISTRY/esp-idf-doc-env-v5.0:2-2" + ESP_DOCS_ENV_IMAGE: "$CI_DOCKER_REGISTRY/esp-idf-doc-env-v5.3:1-1" ESP_DOCS_PATH: "$CI_PROJECT_DIR" TEST_DIR: "$CI_PROJECT_DIR" @@ -57,6 +56,7 @@ after_script: .before_script_build_jobs: before_script: + - pip install idf-component-manager --upgrade - pip install "idf_build_apps~=1.0.1" .check_idf_ver: &check_idf_ver | @@ -69,8 +69,8 @@ after_script: cd ${IDF_PATH} export IDF_DESCRIBE=$(git describe) export IDF_VERSION=${IDF_DESCRIBE%-*} - echo "${IDF_VERSION}" >> ${TEST_DIR}/idf_version_info.txt - echo "${IDF_VERSION}" + echo "$IDF_VERSION" >> $TEST_DIR/idf_version_info.txt + echo "ESP-IDF: $IDF_VERSION" fi # Note: this script builds the folder against all targets and then deletes @@ -160,7 +160,6 @@ build_idf_v5.0: TEST_TARGETS: "esp32 esp32s2 esp32s3 esp32c2 esp32c3" .target_test_template: - image: $TARGET_TEST_ENV_IMAGE stage: target_test timeout: 1 hour variables: diff --git a/docs/_static/diag_frame.diag b/docs/_static/diag_frame.diag index f27add3..5ba19c6 100644 --- a/docs/_static/diag_frame.diag +++ b/docs/_static/diag_frame.diag @@ -2,10 +2,10 @@ blockdiag mb_float_frame { # global properties - span_width = 2; + span_width = 5; span_height = 5; - node_height = 25; - default_fontsize = 16; + node_height = 30; + default_fontsize = 15; default_group_color = lightgrey; class spacer [shape=none, width=10]; # tuning node properties and connections diff --git a/docs/_static/modbus_docs_versions.js b/docs/_static/modbus_docs_versions.js index ab4e07f..0e12a9f 100644 --- a/docs/_static/modbus_docs_versions.js +++ b/docs/_static/modbus_docs_versions.js @@ -1,6 +1,6 @@ var DOCUMENTATION_VERSIONS = { DEFAULTS: { has_targets: true, - supported_targets: [ "esp32", "esp32s2", "esp32s3", "esp32c2","esp32c3", "esp32c6", "esp32s2", "esp32s3, esp32p4" ] + supported_targets: [ "esp32", "esp32s2", "esp32s3", "esp32c2","esp32c3", "esp32c5", "esp32c6", "esp32s2", "esp32s3, esp32p4" ] }, VERSIONS: [ { name: "latest" }, @@ -15,6 +15,7 @@ var DOCUMENTATION_VERSIONS = { { text: "ESP32-C3", value: "esp32c3"}, { text: "ESP32-C6", value: "esp32c6"}, { text: "ESP32-H2", value: "esp32h2"}, - { text: "ESP32-P4", value: "esp32p4"} + { text: "ESP32-P4", value: "esp32p4"}, + { text: "ESP32-C5", value: "esp32c5"} ] }; diff --git a/docs/_static/modbus_frame_examples.diag b/docs/_static/modbus_frame_examples.diag index acef030..c9eb2a2 100644 --- a/docs/_static/modbus_frame_examples.diag +++ b/docs/_static/modbus_frame_examples.diag @@ -4,7 +4,7 @@ blockdiag mb_master_frames { # global properties span_width = 5; span_height = 5; - node_height = 25; + node_height = 30; default_group_color = lightgrey; default_fontsize = 15; # tuning node properties and connections @@ -29,33 +29,33 @@ blockdiag mb_master_frames { style = dashed; 64bit_notes; } - 16bit_notes[label="UINT16, INT16 VALUE = 0x3039 = (uint16_t)12345", width=600, color=orange, shape = roundedbox]; - req_u16_hd1[label= "TX:| UID | FC | REG_START | REG_LEN | CRC |", color=lightyellow, width=380, colwidth=2, shape = roundedbox ,group=16bit_packets]; - req_u16_frm1[label="TX:| 01 | 03 | 00 04 | 00 02 | 85 CA |", color=lightgrey, width=380, colwidth=2,group=16bit_packets]; - rsp_u16_hd1[label= "RX:| UID | FC | LEN | UINT16_AB1 | UINT16_AB2 | CRC |", color=lightyellow, width=380, colwidth=2, shape = roundedbox ,group=16bit_packets]; - rsp_u16_frm1[label="RX:| 01 | 03 | 04 | 30 39 | 30 39 | F1 2C |", color=lightgrey, width=380, colwidth=2,group=16bit_packets]; - rsp_u16_hd2[label= "RX:| UID | FC | LEN | UINT16_BA1 | UINT16_BA2 | CRC |\n ", color=lightyellow, width=380, colwidth=2, shape = roundedbox, group=16bit_packets]; - rsp_u16_frm2[label="RX:| 01 | 03 | 04 | 39 30 | 39 30 | E4 E4 |\n", color=lightgrey, width=380, colwidth=2,group=16bit_packets]; - 32bit_notes[label="(UINT32, INT32) FLOAT32 VALUE = 0x4640e400 = 12345.0", width=600, color=lightgreen, shape = roundedbox]; - req_fl_hd1[label= "TX:| UID | FC | REG_START | REG_LEN | CRC |", color=lightyellow, width=380, colwidth=2, shape = roundedbox ,group=32bit_packets]; - req_fl_frm1[label="TX:| 01 | 03 | 00 XX | 00 04 | C5 CB |", color=lightgrey, width=380, colwidth=2,group=32bit_packets]; - rsp_fl_hd1[label= "RX:| UID | FC | LEN | FLOAT_ABCD1 | FLOAT_ABCD2 | CRC |", color=lightyellow, width=380, colwidth=2, shape = roundedbox ,group=32bit_packets]; - rsp_fl_frm1[label="RX:| 01 | 03 | 08 | E4 00 46 40 | E4 00 46 40 | 90 65 |", color=lightgrey, width=380, colwidth=2,group=32bit_packets]; - rsp_fl_hd2[label= "RX:| UID | FC | LEN | FLOAT_CDAB1 | FLOAT_CDAB2 | CRC |\n ", color=lightyellow, width=380, colwidth=2, shape = roundedbox, group=32bit_packets]; - rsp_fl_frm2[label="RX:| 01 | 03 | 08 | 46 40 E4 00 | 46 40 E4 00 | 18 71 |\n", color=lightgrey, width=380, colwidth=2,group=32bit_packets]; - rsp_fl_hd3[label= "RX:| UID | FC | LEN | FLOAT_BADC1 | FLOAT_BADC2 | CRC |\n ", color=lightyellow, width=380, colwidth=2, shape = roundedbox, group=32bit_packets]; - rsp_fl_frm3[label="RX:| 01 | 03 | 08 | 00 E4 40 46 | 00 E4 40 46 | 46 D3 |\n", color=lightgrey, width=380, colwidth=2,group=32bit_packets]; - rsp_fl_hd4[label= "RX:| UID | FC | LEN | FLOAT_DCAB1 | FLOAT_DCAB2 | CRC |\n ", color=lightyellow, width=380, colwidth=2, shape = roundedbox, group=32bit_packets]; - rsp_fl_frm4[label="RX:| 01 | 03 | 08 | 40 46 00 E4 | 40 46 00 E4 | 32 6B |\n", color=lightgrey, width=380, colwidth=2,group=32bit_packets]; - 64bit_notes[label="(UINT64, INT64) FLOAT64 VALUE = 0x40c81c8000000000 = 12345.0", width=600, color=lightblue, shape = roundedbox]; - req_dbl_hd1[label= "TX:| UID | FC | REG_START | REG_LEN | CRC |", color=lightyellow, width=380, colwidth=2, shape = roundedbox ,group=64bit_packets]; - req_dbl_frm1[label="TX:| 01 | 03 | 00 28 | 00 08 | C4 04 |", color=lightgrey, width=380, colwidth=2,group=64bit_packets]; - rsp_dbl_hd1[label= "RX:| UID | FC | LEN | DOUBLE_ABCDEFGH1 | DOUBLE_ABCDEFGH2 | CRC |", color=lightyellow, width=380, colwidth=2, shape = roundedbox ,group=64bit_packets]; - rsp_dbl_frm1[label="RX:| 01 | 03 | 10 | 00 00 00 00 1C 80 40 C8 | 00 00 00 00 1C 80 40 C8 | 9F 4B |", color=lightgrey, width=380, colwidth=2,group=64bit_packets]; - rsp_dbl_hd2[label= "RX:| UID | FC | LEN | DOUBLE_HGFEDCBA1 | DOUBLE_HGFEDCBA2 | CRC |\n ", color=lightyellow, width=380, colwidth=2, shape = roundedbox, group=64bit_packets]; - rsp_dbl_frm2[label="RX:| 01 | 03 | 10 | C8 40 80 1C 00 00 00 00 | C8 40 80 1C 00 00 00 00 | DF D3 |\n", color=lightgrey, width=380, colwidth=2,group=64bit_packets]; - rsp_dbl_hd3[label= "RX:| UID | FC | LEN | DOUBLE_GHEFCDAB1 | DOUBLE_GHEFCDAB2 | CRC |\n ", color=lightyellow, width=380, colwidth=2, shape = roundedbox, group=64bit_packets]; - rsp_dbl_frm3[label="RX:| 01 | 03 | 10 | 40 C8 1C 80 00 00 00 00 | 40 C8 1C 80 00 00 00 00 | B1 9C |\n", color=lightgrey, width=380, colwidth=2,group=64bit_packets]; - rsp_dbl_hd4[label= "RX:| UID | FC | LEN | DOUBLE_BADCFEHG1 | DOUBLE_BADCFEHG2 | CRC |\n ", color=lightyellow, width=380, colwidth=2, shape = roundedbox, group=64bit_packets]; - rsp_dbl_frm4[label="RX:| 01 | 03 | 10 | 00 00 00 00 80 1C C8 40 | 00 00 00 00 80 1C C8 40 | 86 94 |\n", color=lightgrey, width=380, colwidth=2,group=64bit_packets]; + 16bit_notes[label="(UINT16, INT16) VALUE = 0x3039 = 12345", width=600, color=orange, shape = roundedbox]; + req_u16_hd1[label= "TX:| UID | FC | REG_START | REG_LEN | CRC |", color=lightyellow, width=520, colwidth=2, shape = roundedbox ,group=16bit_packets]; + req_u16_frm1[label="TX:| 01 | 03 | 00 04 | 00 02 | 85 CA |", color=lightgrey, width=540, colwidth=2,group=16bit_packets]; + rsp_u16_hd1[label= "RX:| UID | FC | LEN | UINT16_AB1 | UINT16_AB2 | CRC |", color=lightyellow, width=540, colwidth=2, shape = roundedbox ,group=16bit_packets]; + rsp_u16_frm1[label="RX:| 01 | 03 | 04 | 30 39 | 30 39 | F1 2C |", color=lightgrey, width=540, colwidth=2,group=16bit_packets]; + rsp_u16_hd2[label= "RX:| UID | FC | LEN | UINT16_BA1 | UINT16_BA2 | CRC |\n ", color=lightyellow, width=540, colwidth=2, shape = roundedbox, group=16bit_packets]; + rsp_u16_frm2[label="RX:| 01 | 03 | 04 | 39 30 | 39 30 | E4 E4 |\n", color=lightgrey, width=540, colwidth=2,group=16bit_packets]; + 32bit_notes[label="(UINT32, INT32, FLOAT32) VALUE = 0x4640e400 = 12345.0", width=600, color=lightgreen, shape = roundedbox]; + req_fl_hd1[label= "TX:| UID | FC | REG_START | REG_LEN | CRC |", color=lightyellow, width=540, colwidth=2, shape = roundedbox ,group=32bit_packets]; + req_fl_frm1[label="TX:| 01 | 03 | 00 XX | 00 04 | C5 CB |", color=lightgrey, width=540, colwidth=2,group=32bit_packets]; + rsp_fl_hd1[label= "RX:| UID | FC | LEN | FLOAT_ABCD1 | FLOAT_ABCD2 | CRC |", color=lightyellow, width=540, colwidth=2, shape = roundedbox ,group=32bit_packets]; + rsp_fl_frm1[label="RX:| 01 | 03 | 08 | E4 00 46 40 | E4 00 46 40 | 90 65 |", color=lightgrey, width=540, colwidth=2,group=32bit_packets]; + rsp_fl_hd2[label= "RX:| UID | FC | LEN | FLOAT_CDAB1 | FLOAT_CDAB2 | CRC |\n ", color=lightyellow, width=540, colwidth=2, shape = roundedbox, group=32bit_packets]; + rsp_fl_frm2[label="RX:| 01 | 03 | 08 | 46 40 E4 00 | 46 40 E4 00 | 18 71 |\n", color=lightgrey, width=540, colwidth=2,group=32bit_packets]; + rsp_fl_hd3[label= "RX:| UID | FC | LEN | FLOAT_BADC1 | FLOAT_BADC2 | CRC |\n ", color=lightyellow, width=540, colwidth=2, shape = roundedbox, group=32bit_packets]; + rsp_fl_frm3[label="RX:| 01 | 03 | 08 | 00 E4 40 46 | 00 E4 40 46 | 46 D3 |\n", color=lightgrey, width=540, colwidth=2,group=32bit_packets]; + rsp_fl_hd4[label= "RX:| UID | FC | LEN | FLOAT_DCAB1 | FLOAT_DCAB2 | CRC |\n ", color=lightyellow, width=540, colwidth=2, shape = roundedbox, group=32bit_packets]; + rsp_fl_frm4[label="RX:| 01 | 03 | 08 | 40 46 00 E4 | 40 46 00 E4 | 32 6B |\n", color=lightgrey, width=540, colwidth=2,group=32bit_packets]; + 64bit_notes[label="(UINT64, INT64, FLOAT64) VALUE = 0x40c81c8000000000 = 12345.0", width=600, color=lightblue, shape = roundedbox]; + req_dbl_hd1[label= "TX:| UID | FC | REG_START | REG_LEN | CRC |", color=lightyellow, width=540, colwidth=2, shape = roundedbox ,group=64bit_packets]; + req_dbl_frm1[label="TX:| 01 | 03 | 00 28 | 00 08 | C4 04 |", color=lightgrey, width=540, colwidth=2,group=64bit_packets]; + rsp_dbl_hd1[label= "RX:| UID | FC | LEN | DOUBLE_ABCDEFGH1 | DOUBLE_ABCDEFGH2 | CRC |", color=lightyellow, width=540, colwidth=2, shape = roundedbox ,group=64bit_packets]; + rsp_dbl_frm1[label="RX:| 01 | 03 | 10 | 00 00 00 00 1C 80 40 C8 | 00 00 00 00 1C 80 40 C8 | 9F 4B |", color=lightgrey, width=540, colwidth=2,group=64bit_packets]; + rsp_dbl_hd2[label= "RX:| UID | FC | LEN | DOUBLE_HGFEDCBA1 | DOUBLE_HGFEDCBA2 | CRC |\n ", color=lightyellow, width=540, colwidth=2, shape = roundedbox, group=64bit_packets]; + rsp_dbl_frm2[label="RX:| 01 | 03 | 10 | C8 40 80 1C 00 00 00 00 | C8 40 80 1C 00 00 00 00 | DF D3 |\n", color=lightgrey, width=540, colwidth=2,group=64bit_packets]; + rsp_dbl_hd3[label= "RX:| UID | FC | LEN | DOUBLE_GHEFCDAB1 | DOUBLE_GHEFCDAB2 | CRC |\n ", color=lightyellow, width=540, colwidth=2, shape = roundedbox, group=64bit_packets]; + rsp_dbl_frm3[label="RX:| 01 | 03 | 10 | 40 C8 1C 80 00 00 00 00 | 40 C8 1C 80 00 00 00 00 | B1 9C |\n", color=lightgrey, width=540, colwidth=2,group=64bit_packets]; + rsp_dbl_hd4[label= "RX:| UID | FC | LEN | DOUBLE_BADCFEHG1 | DOUBLE_BADCFEHG2 | CRC |\n ", color=lightyellow, width=540, colwidth=2, shape = roundedbox, group=64bit_packets]; + rsp_dbl_frm4[label="RX:| 01 | 03 | 10 | 00 00 00 00 80 1C C8 40 | 00 00 00 00 80 1C C8 40 | 86 94 |\n", color=lightgrey, width=540, colwidth=2,group=64bit_packets]; } diff --git a/docs/en/overview_messaging_and_mapping.rst b/docs/en/overview_messaging_and_mapping.rst index 4a44cc1..dd235ed 100644 --- a/docs/en/overview_messaging_and_mapping.rst +++ b/docs/en/overview_messaging_and_mapping.rst @@ -12,6 +12,39 @@ The Modbus serial communication protocol is de facto standard protocol widely us .. note:: This documentation (and included code snippets) requires some familiarity with the Modbus protocol. Refer to the Modbus Organization's with protocol specifications for specifics :ref:`modbus_organization`. +.. _modbus_supported_communication_options: + +Modbus Supported Communication Options +-------------------------------------- + +The Modbus library supports the standard communication options as per Modbus specification stated below. + +.. list-table:: Standard Modbus communication options + :widths: 10 90 + :header-rows: 1 + + * - Modbus option + - Description of the option + * - RTU communication + - * 1 start bit + * 8 data bits, least significant bit sent first + * 1 bit for even / odd parity-no bit for no parity + * 1 stop bit if parity is used, 2 stop bits if no parity + * Cyclical Redundancy Check (CRC) + * - ASCII communication + - * 1 start bit + * 7-8 data bits, least significant bit sent first + * 1 bit for even / odd parity-no bit for no parity + * 1 stop bit if parity is used, 2 stop bits if no parity + * Longitudinal Redundancy Check (LRC) + * - TCP communication + - * Communications between client (master) - server (slave) over TCP/IP networks + * Connection uses the standard port 502 + * The frames do not require checksum calculation (provided by lower layers) + +Some vendors may use subset of communication options. In this case the detailed information is clarified in the device manual and it is possible to override the standard communication options for support of such devices. +Please refer to :ref:`modbus_api_slave_setup_communication_options`, :ref:`modbus_api_master_setup_communication_options` for more information. + Messaging Model And Data Mapping -------------------------------- @@ -227,7 +260,7 @@ The extended data types are used to define all possible combinations of groupped - Double BADCFEHG floating point, little endian, reversed register order - Little endian -.. note:: The support for the extended data types should be enabled using the option ``CONFIG_FMB_MASTER_TIMEOUT_MS_RESPOND`` in kconfig menu. +.. note:: The support for the extended data types should be enabled using the option ``CONFIG_FMB_EXT_TYPE_SUPPORT`` in kconfig menu. The below diagrams show how the extended data types appear on network layer. diff --git a/docs/en/slave_api_overview.rst b/docs/en/slave_api_overview.rst index 98e0db4..7a08b48 100644 --- a/docs/en/slave_api_overview.rst +++ b/docs/en/slave_api_overview.rst @@ -101,7 +101,7 @@ Example initialization of mapped values: Slave Communication ^^^^^^^^^^^^^^^^^^^ -The function below is used to start Modbus controller interface and allows communication. +The function below is used to start Modbus controller interface and allows communication. :cpp:func:`mbc_slave_start` diff --git a/docs/generate_docs b/docs/generate_docs index f5bdd5d..ae86890 100755 --- a/docs/generate_docs +++ b/docs/generate_docs @@ -1,7 +1,17 @@ #!/bin/bash -rm -rf docs -build-docs --target esp32 --language en && true +exit_if_error() { + local exit_code=$1 + shift + [[ $exit_code ]] && # do nothing if no error code passed + ((exit_code != 0)) && { # do nothing if error code is 0 + printf 'ERROR: %s\n' "$@" >&2 + exit "$exit_code" + } +} + +rm -rf _build +build-docs --target esp32 --language en || exit_if_error $? "Documentation build fail." # Modifes target field of html files ELEMENT="