rodbus Namespace Reference

main namespace for the rodbus library More...

Namespaces
namespace	functional
	helpers functions to create interface implementations using lambdas

Classes
class	AddressFilter
	Filter used to restrict which IP addresses may communicate with a server. More...
struct	AddressRange
	Range of 16-bit addresses sent in a request from the client to the server. More...
class	AuthorizationHandler
	User implemented interface defines which request and roles are allowed for different functions when implementing Modbus security. More...
class	BitReadCallback
	Callbacks received when reading coils or discrete inputs. More...
struct	BitValue
	Bit value and its address. More...
class	BitValueIterator
	Iterator over BitValue instances. More...
class	ClientChannel
	Abstract representation of a client communication channel. More...
class	ClientStateListener
	Callback for monitoring the state of a TCP/TLS connection state. More...
class	Database
	Class used to add, remove, update, and retrieve values. More...
class	DatabaseCallback
	Callback used to access the internal database while it is locked. More...
struct	DecodeLevel
	Controls the decoding of transmitted and received data at the application, frame, and physical layer. More...
class	DeviceMap
	Maps endpoint handlers to Modbus address. More...
class	Logger
	Logging interface that receives the log messages and writes them somewhere. More...
class	Logging
	Provides a static method for configuring logging. More...
struct	LoggingConfig
	Logging configuration options. More...
class	ParamException
	Exception type corresponding to the underlying error enum ParamError. More...
class	PortStateListener
	Callback interface for receiving updates about the state of a serial port. More...
class	RegisterReadCallback
	Callbacks received when reading holding or input registers. More...
struct	RegisterValue
	Register value and its address. More...
class	RegisterValueIterator
	Iterator over RegisterValue instances. More...
class	RequestException
	Exception type corresponding to the underlying error enum RequestError. More...
struct	RequestParam
	Address and timeout parameters for requests. More...
struct	RetryStrategy
	Retry strategy configuration. More...
class	Runtime
	Handle to the underlying runtime. More...
struct	RuntimeConfig
	Runtime configuration. More...
struct	SerialPortSettings
	Serial port settings. More...
class	Server
	Handle to the running server. The server runs on a background task until this class is destroyed. More...
struct	TlsClientConfig
	TLS client configuration. More...
struct	TlsServerConfig
	TLS server configuration. More...
class	WriteCallback
	Callback methods received from asynchronous write operations. More...
class	WriteHandler
	Interface used to handle write requests received from the client. More...
struct	WriteResult
	Describes to the server if a write operation was successful or not. More...

Enumerations
enum class	ParamError {   ok = 0 , no_support = 1 , null_parameter = 2 , logging_already_configured = 3 ,   runtime_creation_failure = 4 , runtime_destroyed = 5 , runtime_cannot_block_within_async = 6 , invalid_ip_address = 7 ,   invalid_range = 8 , invalid_request = 9 , invalid_index = 10 , server_bind_error = 11 ,   invalid_unit_id = 12 , invalid_peer_certificate = 13 , invalid_local_certificate = 14 , invalid_private_key = 15 ,   invalid_dns_name = 16 , bad_tls_config = 17 , shutdown = 18 , invalid_utf8 = 19 ,   too_many_requests = 20 }
	Error type that indicates a bad parameter or bad programmer logic. More...
enum class	Nothing { nothing = 0 }
	A single value enum which is used as a placeholder for futures that don't return a value. More...
enum class	AppDecodeLevel { nothing = 0 , function_code = 1 , data_headers = 2 , data_values = 3 }
	Controls how transmitted and received message at the application layer are decoded at the INFO log level. More...
enum class	FrameDecodeLevel { nothing = 0 , header = 1 , payload = 2 }
	Controls how the transmitted and received frames are decoded at the INFO log level. More...
enum class	PhysDecodeLevel { nothing = 0 , length = 1 , data = 2 }
	Controls how data transmitted at the physical layer (TCP, serial, etc) is logged. More...
enum class	RequestError {   ok = 0 , shutdown = 1 , no_connection = 2 , response_timeout = 3 ,   bad_request = 4 , bad_response = 5 , io_error = 6 , bad_framing = 7 ,   internal_error = 8 , bad_argument = 9 , modbus_exception_illegal_function = 10 , modbus_exception_illegal_data_address = 11 ,   modbus_exception_illegal_data_value = 12 , modbus_exception_server_device_failure = 13 , modbus_exception_acknowledge = 14 , modbus_exception_server_device_busy = 15 ,   modbus_exception_memory_parity_error = 16 , modbus_exception_gateway_path_unavailable = 17 , modbus_exception_gateway_target_device_failed_to_respond = 18 , modbus_exception_unknown = 19 }
	Error information returned from asynchronous functions calls. More...
enum class	ModbusException {   illegal_function = 1 , illegal_data_address = 2 , illegal_data_value = 3 , server_device_failure = 4 ,   acknowledge = 5 , server_device_busy = 6 , memory_parity_error = 8 , gateway_path_unavailable = 10 ,   gateway_target_device_failed_to_respond = 11 , unknown = 255 }
	Error information returned during asynchronous API calls. More...
enum class	DataBits { five = 0 , six = 1 , seven = 2 , eight = 3 }
	Number of bits per character. More...
enum class	FlowControl { none = 0 , software = 1 , hardware = 2 }
	Flow control modes. More...
enum class	Parity { none = 0 , odd = 1 , even = 2 }
	Parity checking modes. More...
enum class	StopBits { one = 0 , two = 1 }
	Number of stop bits. More...
enum class	MinTlsVersion { v12 = 0 , v13 = 1 }
	Minimum TLS version to allow. More...
enum class	CertificateMode { authority_based = 0 , self_signed = 1 }
	Determines how the certificate(s) presented by the peer are validated. More...
enum class	LogLevel {   error = 0 , warn = 1 , info = 2 , debug = 3 ,   trace = 4 }
	Log level. More...
enum class	LogOutputFormat { text = 0 , json = 1 }
	Describes how each log event is formatted. More...
enum class	TimeFormat { none = 0 , rfc_3339 = 1 , system = 2 }
	Describes if and how the time will be formatted in log messages. More...
enum class	ClientState {   disabled = 0 , connecting = 1 , connected = 2 , wait_after_failed_connect = 3 ,   wait_after_disconnect = 4 , shutdown = 5 }
	State of the client connection. More...
enum class	PortState { disabled = 0 , wait = 1 , open = 2 , shutdown = 3 }
	State of the serial port. More...
enum class	Authorization { allow = 0 , deny = 1 }
	Authorization result used by AuthorizationHandler. More...

Functions
const char *	to_string (ParamError value)
	convert an instance of enum ParamError into a C-style string More...
const char *	to_string (Nothing value)
	convert an instance of enum Nothing into a C-style string More...
const char *	to_string (AppDecodeLevel value)
	convert an instance of enum AppDecodeLevel into a C-style string More...
const char *	to_string (FrameDecodeLevel value)
	convert an instance of enum FrameDecodeLevel into a C-style string More...
const char *	to_string (PhysDecodeLevel value)
	convert an instance of enum PhysDecodeLevel into a C-style string More...
const char *	to_string (RequestError value)
	convert an instance of enum RequestError into a C-style string More...
const char *	to_string (ModbusException value)
	convert an instance of enum ModbusException into a C-style string More...
const char *	to_string (DataBits value)
	convert an instance of enum DataBits into a C-style string More...
const char *	to_string (FlowControl value)
	convert an instance of enum FlowControl into a C-style string More...
const char *	to_string (Parity value)
	convert an instance of enum Parity into a C-style string More...
const char *	to_string (StopBits value)
	convert an instance of enum StopBits into a C-style string More...
const char *	to_string (MinTlsVersion value)
	convert an instance of enum MinTlsVersion into a C-style string More...
const char *	to_string (CertificateMode value)
	convert an instance of enum CertificateMode into a C-style string More...
const char *	to_string (LogLevel value)
	convert an instance of enum LogLevel into a C-style string More...
const char *	to_string (LogOutputFormat value)
	convert an instance of enum LogOutputFormat into a C-style string More...
const char *	to_string (TimeFormat value)
	convert an instance of enum TimeFormat into a C-style string More...
const char *	to_string (ClientState value)
	convert an instance of enum ClientState into a C-style string More...
const char *	to_string (PortState value)
	convert an instance of enum PortState into a C-style string More...
const char *	to_string (Authorization value)
	convert an instance of enum Authorization into a C-style string More...

Variables
constexpr uint64_t	rodbus_version_major = 1
	major version number More...
constexpr uint64_t	rodbus_version_minor = 6
	minor version number More...
constexpr uint64_t	rodbus_version_patch = 0
	patch version number More...
constexpr char const *	rodbus_version_string = "1.6.0-RC1"
	version number as the string major.minor.patch More...

Detailed Description

main namespace for the rodbus library

Enumeration Type Documentation

AppDecodeLevel

enum class rodbus::AppDecodeLevel

strong

Controls how transmitted and received message at the application layer are decoded at the INFO log level.

Application-layer messages are referred to as Protocol Data Units (PDUs) in the specification.

Enumerator
nothing	Decode nothing.
function_code	Decode the function code only.
data_headers	Decode the function code and the general description of the data.
data_values	Decode the function code, the general description of the data and the actual data values.

Authorization

enum class rodbus::Authorization

strong

Authorization result used by AuthorizationHandler.

Enumerator
allow	Client is authorized to perform the operation.
deny	Client is NOT authorized to perform the operation.

CertificateMode

enum class rodbus::CertificateMode

strong

Determines how the certificate(s) presented by the peer are validated.

The certificate is validated when the peer presents it during the handshake, before the peer's handshake signature is verified. The handshake fails if either check fails.

Enumerator
authority_based	Validates the peer certificate against one or more configured trust anchors. This mode uses the default certificate verifier in `rustls` to ensure that the chain of certificates presented by the peer is valid against one of the configured trust anchors. A client checks @ref TlsClientConfig.dns_name against the SAN extension of the certificate or, if the certificate has no SAN extension, against its Common Name, unless @ref TlsClientConfig.allow_server_name_wildcard is set and the name is '*', which skips the name check. A server doesn't check the client's name.
self_signed	Validates that the peer presents a single certificate which is a byte-for-byte match against the configured peer certificate. The certificate is parsed only to ensure that the `NotBefore` and `NotAfter` are valid for the current system time.

ClientState

enum class rodbus::ClientState

strong

State of the client connection.

Used by the ClientStateListener.

Enumerator
disabled	Client is disabled and idle until enabled.
connecting	Client is trying to establish a connection to the remote device.
connected	Client is connected to the remote device.
wait_after_failed_connect	Failed to establish a connection, waiting before retrying.
wait_after_disconnect	Client was disconnected, waiting before retrying.
shutdown	Client is shutting down.

DataBits

enum class rodbus::DataBits

strong

Number of bits per character.

Enumerator
five	5 bits per character
six	6 bits per character
seven	7 bits per character
eight	8 bits per character

FlowControl

enum class rodbus::FlowControl

strong

Flow control modes.

Enumerator
none	No flow control.
software	Flow control using XON/XOFF bytes.
hardware	Flow control using RTS/CTS signals.

FrameDecodeLevel

enum class rodbus::FrameDecodeLevel

strong

Controls how the transmitted and received frames are decoded at the INFO log level.

Transport-specific framing wraps the application-layer traffic. You'll see these frames called ADUs in the Modbus specification.

On TCP, this is the MBAP decoding. On serial, this controls the serial line PDU.

Enumerator
nothing	Log nothing.
header	Decode the header.
payload	Decode the header and the raw payload as hexadecimal.

LogLevel

enum class rodbus::LogLevel

strong

Log level.

Used in Logger::on_message() callback to identify the log level of a message.

Enumerator
error	Error log level.
warn	Warning log level.
info	Information log level.
debug	Debugging log level.
trace	Trace log level.

LogOutputFormat

enum class rodbus::LogOutputFormat

strong

Describes how each log event is formatted.

Enumerator
text	A simple text-based format.
json	Output formatted as JSON.

MinTlsVersion

enum class rodbus::MinTlsVersion

strong

Minimum TLS version to allow.

Enumerator
v12	Allow TLS 1.2 and TLS 1.3.
v13	Allow only TLS 1.3. A peer that doesn't support TLS 1.3 fails the handshake.

ModbusException

enum class rodbus::ModbusException

strong

Error information returned during asynchronous API calls.

Enumerator
illegal_function	The data address received in the query is not an allowable address for the server.
illegal_data_address	The data address received in the query is not an allowable address for the server.
illegal_data_value	A value contained in the request is not an allowable value for server.
server_device_failure	An unrecoverable error occurred while the server was attempting to perform the requested action.
acknowledge	Specialized use in conjunction with programming commands. The server has accepted the request and is processing it.
server_device_busy	Specialized use in conjunction with programming commands. The server is engaged in processing a long-duration program command, try again later.
memory_parity_error	Specialized use in conjunction with function codes 20 and 21 and reference type 6, to indicate that the extended file area failed to pass a consistency check. The server attempted to read a record file, but detected a parity error in the memory.
gateway_path_unavailable	Specialized use in conjunction with gateways, indicates that the gateway was unable to allocate an internal communication path from the input port to the output port for processing the request. Usually means that the gateway is mis-configured or overloaded.
gateway_target_device_failed_to_respond	Specialized use in conjunction with gateways, indicates that no response was obtained from the target device. Usually means that the device is not present on the network.
unknown	The status code is not defined in the Modbus specification, refer to the raw exception code to see what the server sent.

Nothing

enum class rodbus::Nothing

strong

A single value enum which is used as a placeholder for futures that don't return a value.

Enumerator
nothing	the only value this enum has

ParamError

enum class rodbus::ParamError

strong

Error type that indicates a bad parameter or bad programmer logic.

Enumerator
ok	Success, i.e. no error occurred.
no_support	The FFI library was compiled without support for this feature.
null_parameter	Null parameter.
logging_already_configured	Logging can only be configured once.
runtime_creation_failure	Failed to create Tokio runtime.
runtime_destroyed	Runtime was already disposed of.
runtime_cannot_block_within_async	Runtime cannot execute blocking call within asynchronous context.
invalid_ip_address	Invalid IP address.
invalid_range	Invalid Modbus address range.
invalid_request	Invalid Modbus request.
invalid_index	Invalid index.
server_bind_error	Server failed to bind to the specified port.
invalid_unit_id	The specified unit id is not associated to this server.
invalid_peer_certificate	Invalid peer certificate file.
invalid_local_certificate	Invalid local certificate file.
invalid_private_key	Invalid private key file.
invalid_dns_name	Invalid DNS name.
bad_tls_config	Bad TLS configuration.
shutdown	The task has been shutdown.
invalid_utf8	String argument was not valid UTF-8.
too_many_requests	Number of requests exceeds configured limit.

Parity

enum class rodbus::Parity

strong

Parity checking modes.

Enumerator
none	No parity bit.
odd	Parity bit sets odd number of 1 bits.
even	Parity bit sets even number of 1 bits.

PhysDecodeLevel

enum class rodbus::PhysDecodeLevel

strong

Controls how data transmitted at the physical layer (TCP, serial, etc) is logged.

Enumerator
nothing	Log nothing.
length	Log only the length of data that is sent and received.
data	Log the length and the actual data that is sent and received.

PortState

enum class rodbus::PortState

strong

State of the serial port.

Used by the PortStateListener.

Enumerator
disabled	Disabled until enabled.
wait	Waiting to perform an open retry.
open	Port is open.
shutdown	Task has been shut down.

RequestError

enum class rodbus::RequestError

strong

Error information returned from asynchronous functions calls.

Unlike ParamError, the values here generally represent spontaneous failures that are outside developer control, e.g. network failures, etc

Enumerator
ok	Success, i.e. no error occurred.
shutdown	The channel was shutdown before the operation could complete.
no_connection	The channel had no connection (or open serial port) for the request: it was disabled, connecting, or waiting to retry.
response_timeout	No valid response was received before the timeout.
bad_request	The request was invalid.
bad_response	The response from the server was received but was improperly formatted.
io_error	An I/O error occurred on the underlying stream while performing the request.
bad_framing	A framing error was detected while performing the request.
internal_error	An unspecified internal error occurred while performing the request.
bad_argument	An invalid argument was supplied and the request could not be performed.
modbus_exception_illegal_function	The data address received in the query is not an allowable address for the server.
modbus_exception_illegal_data_address	The data address received in the query is not an allowable address for the server.
modbus_exception_illegal_data_value	A value contained in the request is not an allowable value for server.
modbus_exception_server_device_failure	An unrecoverable error occurred while the server was attempting to perform the requested action.
modbus_exception_acknowledge	Specialized use in conjunction with programming commands. The server has accepted the request and is processing it.
modbus_exception_server_device_busy	Specialized use in conjunction with programming commands. The server is engaged in processing a long-duration program command, try again later.
modbus_exception_memory_parity_error	Specialized use in conjunction with function codes 20 and 21 and reference type 6, to indicate that the extended file area failed to pass a consistency check. The server attempted to read a record file, but detected a parity error in the memory.
modbus_exception_gateway_path_unavailable	Specialized use in conjunction with gateways, indicates that the gateway was unable to allocate an internal communication path from the input port to the output port for processing the request. Usually means that the gateway is mis-configured or overloaded.
modbus_exception_gateway_target_device_failed_to_respond	Specialized use in conjunction with gateways, indicates that no response was obtained from the target device. Usually means that the device is not present on the network.
modbus_exception_unknown	The status code is not defined in the Modbus specification, refer to the raw exception code to see what the server sent.

StopBits

enum class rodbus::StopBits

strong

Number of stop bits.

Enumerator
one	One stop bit.
two	Two stop bits.

TimeFormat

enum class rodbus::TimeFormat

strong

Describes if and how the time will be formatted in log messages.

Enumerator
none	Don't format the timestamp as part of the message.
rfc_3339	Format the time using RFC 3339.
system	Format the time in a human readable format e.g. 'Jun 25 14:27:12.955'.

Function Documentation

to_string() [1/19]

const char * rodbus::to_string

(

AppDecodeLevel

value

)

convert an instance of enum AppDecodeLevel into a C-style string

Parameters

value

enum value

Returns

C-style string constant

to_string() [2/19]

const char * rodbus::to_string

(

Authorization

value

)

convert an instance of enum Authorization into a C-style string

Parameters

value

enum value

Returns

C-style string constant

to_string() [3/19]

const char * rodbus::to_string

(

CertificateMode

value

)

convert an instance of enum CertificateMode into a C-style string

Parameters

value

enum value

Returns

C-style string constant

to_string() [4/19]

const char * rodbus::to_string

(

ClientState

value

)

convert an instance of enum ClientState into a C-style string

Parameters

value

enum value

Returns

C-style string constant

to_string() [5/19]

const char * rodbus::to_string

(

DataBits

value

)

convert an instance of enum DataBits into a C-style string

Parameters

value

enum value

Returns

C-style string constant

to_string() [6/19]

const char * rodbus::to_string

(

FlowControl

value

)

convert an instance of enum FlowControl into a C-style string

Parameters

value

enum value

Returns

C-style string constant

to_string() [7/19]

const char * rodbus::to_string

(

FrameDecodeLevel

value

)

convert an instance of enum FrameDecodeLevel into a C-style string

Parameters

value

enum value

Returns

C-style string constant

to_string() [8/19]

const char * rodbus::to_string

(

LogLevel

value

)

convert an instance of enum LogLevel into a C-style string

Parameters

value

enum value

Returns

C-style string constant

to_string() [9/19]

const char * rodbus::to_string

(

LogOutputFormat

value

)

convert an instance of enum LogOutputFormat into a C-style string

Parameters

value

enum value

Returns

C-style string constant

to_string() [10/19]

const char * rodbus::to_string

(

MinTlsVersion

value

)

convert an instance of enum MinTlsVersion into a C-style string

Parameters

value

enum value

Returns

C-style string constant

to_string() [11/19]

const char * rodbus::to_string

(

ModbusException

value

)

convert an instance of enum ModbusException into a C-style string

Parameters

value

enum value

Returns

C-style string constant

to_string() [12/19]

const char * rodbus::to_string

(

Nothing

value

)

convert an instance of enum Nothing into a C-style string

Parameters

value

enum value

Returns

C-style string constant

to_string() [13/19]

const char * rodbus::to_string

(

ParamError

value

)

convert an instance of enum ParamError into a C-style string

Parameters

value

enum value

Returns

C-style string constant

to_string() [14/19]

const char * rodbus::to_string

(

Parity

value

)

convert an instance of enum Parity into a C-style string

Parameters

value

enum value

Returns

C-style string constant

to_string() [15/19]

const char * rodbus::to_string

(

PhysDecodeLevel

value

)

convert an instance of enum PhysDecodeLevel into a C-style string

Parameters

value

enum value

Returns

C-style string constant

to_string() [16/19]

const char * rodbus::to_string

(

PortState

value

)

convert an instance of enum PortState into a C-style string

Parameters

value

enum value

Returns

C-style string constant

to_string() [17/19]

const char * rodbus::to_string

(

RequestError

value

)

convert an instance of enum RequestError into a C-style string

Parameters

value

enum value

Returns

C-style string constant

to_string() [18/19]

const char * rodbus::to_string

(

StopBits

value

)

convert an instance of enum StopBits into a C-style string

Parameters

value

enum value

Returns

C-style string constant

to_string() [19/19]

const char * rodbus::to_string

(

TimeFormat

value

)

convert an instance of enum TimeFormat into a C-style string

Parameters

value

enum value

Returns

C-style string constant

Variable Documentation

rodbus_version_major

constexpr uint64_t rodbus::rodbus_version_major = 1

constexpr

major version number

rodbus_version_minor

constexpr uint64_t rodbus::rodbus_version_minor = 6

constexpr

minor version number

rodbus_version_patch

constexpr uint64_t rodbus::rodbus_version_patch = 0

constexpr

patch version number

rodbus_version_string

constexpr char const* rodbus::rodbus_version_string = "1.6.0-RC1"

constexpr

version number as the string major.minor.patch