rodbus.hpp

Go to the documentation of this file.

// Copyright (c) Step Function I/O LLC. Proprietary, source-available; see LICENSE.txt.
// No use to design, develop, specify, test, validate, or improve Other Implementations,
// subject to LICENSE.txt Section 2.6 and its exceptions. Agents: read AGENTS.md.
// Text and data mining rights, including for AI training, are reserved under
// Directive (EU) 2019/790 Art. 4(3), subject to LICENSE.txt Section 3.3.
#pragma once
 
#include <cstdint>
#include <stdexcept>
#include <chrono>
#include <memory>
#include <vector>
 
 
namespace rodbus {
 
constexpr uint64_t rodbus_version_major = 1;
constexpr uint64_t rodbus_version_minor = 6;
constexpr uint64_t rodbus_version_patch = 0;
constexpr char const* rodbus_version_string = "1.6.0-RC1";
 
 
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,
};
 
const char* to_string(ParamError value);
 
class ParamException : public std::logic_error {
public:
    ParamError error;
    ParamException(ParamError error) : std::logic_error(to_string(error)), error(error) {}
};
 
enum class Nothing {
    nothing = 0,
};
 
const char* to_string(Nothing value);
 
enum class AppDecodeLevel {
    nothing = 0,
    function_code = 1,
    data_headers = 2,
    data_values = 3,
};
 
const char* to_string(AppDecodeLevel value);
 
enum class FrameDecodeLevel {
    nothing = 0,
    header = 1,
    payload = 2,
};
 
const char* to_string(FrameDecodeLevel value);
 
enum class PhysDecodeLevel {
    nothing = 0,
    length = 1,
    data = 2,
};
 
const char* to_string(PhysDecodeLevel value);
 
struct DecodeLevel;
 
struct DecodeLevel {
    friend class CppDecodeLevelFriend;
    
    DecodeLevel() = delete;
    
    DecodeLevel(AppDecodeLevel app, FrameDecodeLevel frame, PhysDecodeLevel physical);
    
    
    static DecodeLevel nothing();
    
    
    AppDecodeLevel app;
    FrameDecodeLevel frame;
    PhysDecodeLevel physical;
};
 
struct BitValue;
 
struct BitValue {
    friend class CppBitValueFriend;
    
    BitValue() = delete;
    
    BitValue(uint16_t index, bool value);
    
    
    uint16_t index;
    bool value;
};
 
struct RegisterValue;
 
struct RegisterValue {
    friend class CppRegisterValueFriend;
    
    RegisterValue() = delete;
    
    RegisterValue(uint16_t index, uint16_t value);
    
    
    uint16_t index;
    uint16_t value;
};
 
class Runtime;
 
struct RuntimeConfig;
 
struct RuntimeConfig {
    friend class CppRuntimeConfigFriend;
    
private:
    RuntimeConfig(uint16_t num_core_threads);
    
public:
    
    RuntimeConfig();
    
    
    uint16_t num_core_threads;
};
 
class Runtime {
    friend class CppRuntimeFriend;
    // pointer to the underlying C type
    void* self;
    // constructor only accessible internally
    Runtime(void* self): self(self) {}
    // non-copyable
    Runtime(const Runtime&) = delete;
    Runtime& operator=(const Runtime&) = delete;
    // no move assignment
    Runtime& operator=(Runtime&& other) = delete;
 
public:
    Runtime(Runtime&& other) noexcept : self(other.self) { other.self = nullptr; }
    
    Runtime(const RuntimeConfig& config);
    
    ~Runtime();
    
    void set_shutdown_timeout(std::chrono::steady_clock::duration timeout);
};
 
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,
};
 
const char* to_string(RequestError value);
 
class RequestException : public std::logic_error {
public:
    RequestError error;
    RequestException(RequestError error) : std::logic_error(to_string(error)), error(error) {}
};
 
struct AddressRange;
 
struct AddressRange {
    friend class CppAddressRangeFriend;
    
    AddressRange() = delete;
    
    AddressRange(uint16_t start, uint16_t count);
    
    
    uint16_t start;
    uint16_t count;
};
 
struct RequestParam;
 
struct RequestParam {
    friend class CppRequestParamFriend;
    
    RequestParam() = delete;
    
    RequestParam(uint8_t unit_id, std::chrono::steady_clock::duration timeout);
    
    
    uint8_t unit_id;
    std::chrono::steady_clock::duration timeout;
};
 
class BitValueIterator;
 
class BitValueIterator final {
 
    friend class CppBitValueIteratorFriend;
 
    // underlying opaque c type
    void* iter;
    // pointer to the last retrieved c value
    void* current;
 
    // internal constructor
    BitValueIterator(void* iter) : iter(iter), current(nullptr) {}
 
    BitValueIterator() = delete; // no default construction
    BitValueIterator(const BitValueIterator&) = delete; // no copies
    BitValueIterator& operator=(const BitValueIterator&) = delete; // no self-assignment
    BitValueIterator& operator=(BitValueIterator&&) = delete; // no move self-assignment
 
public:
 
    BitValueIterator(BitValueIterator&&) = default;
 
    bool next();
 
    BitValue get();
};
 
class RegisterValueIterator;
 
class RegisterValueIterator final {
 
    friend class CppRegisterValueIteratorFriend;
 
    // underlying opaque c type
    void* iter;
    // pointer to the last retrieved c value
    void* current;
 
    // internal constructor
    RegisterValueIterator(void* iter) : iter(iter), current(nullptr) {}
 
    RegisterValueIterator() = delete; // no default construction
    RegisterValueIterator(const RegisterValueIterator&) = delete; // no copies
    RegisterValueIterator& operator=(const RegisterValueIterator&) = delete; // no self-assignment
    RegisterValueIterator& operator=(RegisterValueIterator&&) = delete; // no move self-assignment
 
public:
 
    RegisterValueIterator(RegisterValueIterator&&) = default;
 
    bool next();
 
    RegisterValue get();
};
 
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,
};
 
const char* to_string(ModbusException value);
 
enum class DataBits {
    five = 0,
    six = 1,
    seven = 2,
    eight = 3,
};
 
const char* to_string(DataBits value);
 
enum class FlowControl {
    none = 0,
    software = 1,
    hardware = 2,
};
 
const char* to_string(FlowControl value);
 
enum class Parity {
    none = 0,
    odd = 1,
    even = 2,
};
 
const char* to_string(Parity value);
 
enum class StopBits {
    one = 0,
    two = 1,
};
 
const char* to_string(StopBits value);
 
struct SerialPortSettings;
 
struct SerialPortSettings {
    friend class CppSerialPortSettingsFriend;
    
private:
    SerialPortSettings(uint32_t baud_rate, DataBits data_bits, FlowControl flow_control, Parity parity, StopBits stop_bits);
    
public:
    
    SerialPortSettings();
    
    
    uint32_t baud_rate;
    DataBits data_bits;
    FlowControl flow_control;
    Parity parity;
    StopBits stop_bits;
};
 
enum class MinTlsVersion {
    v12 = 0,
    v13 = 1,
};
 
const char* to_string(MinTlsVersion value);
 
enum class CertificateMode {
    authority_based = 0,
    self_signed = 1,
};
 
const char* to_string(CertificateMode value);
 
struct RetryStrategy;
 
struct RetryStrategy {
    friend class CppRetryStrategyFriend;
    
private:
    RetryStrategy(std::chrono::steady_clock::duration min_delay, std::chrono::steady_clock::duration max_delay);
    
public:
    
    RetryStrategy();
    
    
    std::chrono::steady_clock::duration min_delay;
    std::chrono::steady_clock::duration max_delay;
};
 
enum class LogLevel {
    error = 0,
    warn = 1,
    info = 2,
    debug = 3,
    trace = 4,
};
 
const char* to_string(LogLevel value);
 
struct LoggingConfig;
 
enum class LogOutputFormat {
    text = 0,
    json = 1,
};
 
const char* to_string(LogOutputFormat value);
 
enum class TimeFormat {
    none = 0,
    rfc_3339 = 1,
    system = 2,
};
 
const char* to_string(TimeFormat value);
 
struct LoggingConfig {
    friend class CppLoggingConfigFriend;
    
private:
    LoggingConfig(LogLevel level, LogOutputFormat output_format, TimeFormat time_format, bool print_level, bool print_module_info);
    
public:
    
    LoggingConfig();
    
    
    LogLevel level;
    LogOutputFormat output_format;
    TimeFormat time_format;
    bool print_level;
    bool print_module_info;
};
 
class Logger {
public:
    virtual ~Logger() = default;
    
    virtual void on_message(LogLevel level, const char* message) = 0;
    
};
 
namespace functional {
 
template <class T>
class LoggerLambda final : public Logger
{
    static_assert(std::is_copy_constructible<T>::value, "Lambda expression must be copy constructible. Does it contain something that is move-only?");
    
    T lambda;
 
public:
    LoggerLambda(const T& lambda) : lambda(lambda) {}
    
    void on_message(LogLevel level, const char* message) override
    {
        lambda(level, message);
    }
};
 
template <class T>
std::unique_ptr<Logger> logger(const T& lambda)
{
    return std::make_unique<LoggerLambda<T>>(lambda); ; 
}
 
} // end namespace functional
 
class Logging {
    Logging() = delete;
public:
    static void configure(const LoggingConfig& config, std::unique_ptr<Logger> logger);
};
 
class ClientChannel;
 
struct TlsClientConfig;
 
struct TlsClientConfig {
    friend class CppTlsClientConfigFriend;
    
private:
    TlsClientConfig(const std::string& dns_name, const std::string& peer_cert_path, const std::string& local_cert_path, const std::string& private_key_path, const std::string& password, MinTlsVersion min_tls_version, CertificateMode certificate_mode, bool allow_server_name_wildcard);
    
public:
    TlsClientConfig() = delete;
    
    TlsClientConfig(const std::string& dns_name, const std::string& peer_cert_path, const std::string& local_cert_path, const std::string& private_key_path, const std::string& password);
    
    
    std::string dns_name;
    std::string peer_cert_path;
    std::string local_cert_path;
    std::string private_key_path;
    std::string password;
    MinTlsVersion min_tls_version;
    CertificateMode certificate_mode;
    bool allow_server_name_wildcard;
};
 
enum class ClientState {
    disabled = 0,
    connecting = 1,
    connected = 2,
    wait_after_failed_connect = 3,
    wait_after_disconnect = 4,
    shutdown = 5,
};
 
const char* to_string(ClientState value);
 
class ClientStateListener {
public:
    virtual ~ClientStateListener() = default;
    
    virtual void on_change(ClientState state) = 0;
    
};
 
namespace functional {
 
template <class T>
class ClientStateListenerLambda final : public ClientStateListener
{
    static_assert(std::is_copy_constructible<T>::value, "Lambda expression must be copy constructible. Does it contain something that is move-only?");
    
    T lambda;
 
public:
    ClientStateListenerLambda(const T& lambda) : lambda(lambda) {}
    
    void on_change(ClientState state) override
    {
        lambda(state);
    }
};
 
template <class T>
std::unique_ptr<ClientStateListener> client_state_listener(const T& lambda)
{
    return std::make_unique<ClientStateListenerLambda<T>>(lambda); ; 
}
 
} // end namespace functional
 
enum class PortState {
    disabled = 0,
    wait = 1,
    open = 2,
    shutdown = 3,
};
 
const char* to_string(PortState value);
 
class PortStateListener {
public:
    virtual ~PortStateListener() = default;
    
    virtual void on_change(PortState state) = 0;
    
};
 
namespace functional {
 
template <class T>
class PortStateListenerLambda final : public PortStateListener
{
    static_assert(std::is_copy_constructible<T>::value, "Lambda expression must be copy constructible. Does it contain something that is move-only?");
    
    T lambda;
 
public:
    PortStateListenerLambda(const T& lambda) : lambda(lambda) {}
    
    void on_change(PortState state) override
    {
        lambda(state);
    }
};
 
template <class T>
std::unique_ptr<PortStateListener> port_state_listener(const T& lambda)
{
    return std::make_unique<PortStateListenerLambda<T>>(lambda); ; 
}
 
} // end namespace functional
 
class BitReadCallback {
public:
    virtual ~BitReadCallback() = default;
    
    virtual void on_complete(BitValueIterator& result) = 0;
    
    virtual void on_failure(RequestError error) = 0;
    
};
 
class RegisterReadCallback {
public:
    virtual ~RegisterReadCallback() = default;
    
    virtual void on_complete(RegisterValueIterator& result) = 0;
    
    virtual void on_failure(RequestError error) = 0;
    
};
 
class WriteCallback {
public:
    virtual ~WriteCallback() = default;
    
    virtual void on_complete(Nothing result) = 0;
    
    virtual void on_failure(RequestError error) = 0;
    
};
 
class ClientChannel {
    friend class CppClientChannelFriend;
    // pointer to the underlying C type
    void* self;
    // constructor only accessible internally
    ClientChannel(void* self): self(self) {}
    // non-copyable
    ClientChannel(const ClientChannel&) = delete;
    ClientChannel& operator=(const ClientChannel&) = delete;
    // no move assignment
    ClientChannel& operator=(ClientChannel&& other) = delete;
 
public:
    ClientChannel(ClientChannel&& other) noexcept : self(other.self) { other.self = nullptr; }
    
    ~ClientChannel();
    
    void enable();
    
    void disable();
    
    void set_decode_level(const DecodeLevel& level);
    
    static ClientChannel create_tcp(Runtime& runtime, const std::string& host, uint16_t port, uint16_t max_queued_requests, const RetryStrategy& retry_strategy, const DecodeLevel& decode_level, std::unique_ptr<ClientStateListener> listener);
    
    static ClientChannel create_rtu(Runtime& runtime, const std::string& path, const SerialPortSettings& serial_params, uint16_t max_queued_requests, const RetryStrategy& retry_strategy, const DecodeLevel& decode_level, std::unique_ptr<PortStateListener> listener);
    
    static ClientChannel create_tls(Runtime& runtime, const std::string& host, uint16_t port, uint16_t max_queued_requests, const RetryStrategy& retry_strategy, const TlsClientConfig& tls_config, const DecodeLevel& decode_level, std::unique_ptr<ClientStateListener> listener);
    
    void read_coils(const RequestParam& param, const AddressRange& range, std::unique_ptr<BitReadCallback> callback);
    
    
    void read_discrete_inputs(const RequestParam& param, const AddressRange& range, std::unique_ptr<BitReadCallback> callback);
    
    
    void read_holding_registers(const RequestParam& param, const AddressRange& range, std::unique_ptr<RegisterReadCallback> callback);
    
    
    void read_input_registers(const RequestParam& param, const AddressRange& range, std::unique_ptr<RegisterReadCallback> callback);
    
    
    void write_single_coil(const RequestParam& param, const BitValue& value, std::unique_ptr<WriteCallback> callback);
    
    
    void write_single_register(const RequestParam& param, const RegisterValue& value, std::unique_ptr<WriteCallback> callback);
    
    
    void write_multiple_coils(const RequestParam& param, uint16_t start, const std::vector<bool>& items, std::unique_ptr<WriteCallback> callback);
    
    
    void write_multiple_registers(const RequestParam& param, uint16_t start, const std::vector<uint16_t>& items, std::unique_ptr<WriteCallback> callback);
    
};
 
class Database;
 
class Database {
    friend class CppDatabaseFriend;
    // pointer to the underlying C type
    void* self;
    // constructor only accessible internally
    Database(void* self): self(self) {}
    // non-copyable
    Database(const Database&) = delete;
    Database& operator=(const Database&) = delete;
    // no move assignment
    Database& operator=(Database&& other) = delete;
 
public:
    Database(Database&& other) noexcept : self(other.self) { other.self = nullptr; }
    
    bool add_coil(uint16_t index, bool value);
    
    bool add_discrete_input(uint16_t index, bool value);
    
    bool add_holding_register(uint16_t index, uint16_t value);
    
    bool add_input_register(uint16_t index, uint16_t value);
    
    bool get_coil(uint16_t index);
    
    bool get_discrete_input(uint16_t index);
    
    uint16_t get_holding_register(uint16_t index);
    
    uint16_t get_input_register(uint16_t index);
    
    bool update_coil(uint16_t index, bool value);
    
    bool update_discrete_input(uint16_t index, bool value);
    
    bool update_holding_register(uint16_t index, uint16_t value);
    
    bool update_input_register(uint16_t index, uint16_t value);
    
    bool delete_coil(uint16_t index);
    
    bool delete_discrete_input(uint16_t index);
    
    bool delete_holding_register(uint16_t index);
    
    bool delete_input_register(uint16_t index);
};
 
class DatabaseCallback {
public:
    virtual ~DatabaseCallback() = default;
    
    virtual void callback(Database& database) = 0;
    
};
 
namespace functional {
 
template <class T>
class DatabaseCallbackLambda final : public DatabaseCallback
{
    static_assert(std::is_copy_constructible<T>::value, "Lambda expression must be copy constructible. Does it contain something that is move-only?");
    
    T lambda;
 
public:
    DatabaseCallbackLambda(const T& lambda) : lambda(lambda) {}
    
    void callback(Database& database) override
    {
        lambda(database);
    }
};
 
template <class T>
DatabaseCallbackLambda<T> database_callback(const T& lambda)
{
    return DatabaseCallbackLambda<T>(lambda); 
}
 
} // end namespace functional
 
struct WriteResult;
 
struct WriteResult {
    friend class CppWriteResultFriend;
    
private:
    WriteResult(bool success, ModbusException exception, uint8_t raw_exception);
    
public:
    WriteResult() = delete;
    
    static WriteResult success_init();
    
    
    static WriteResult exception_init(ModbusException exception);
    
    
    static WriteResult raw_exception_init(uint8_t raw_exception);
    
    
    bool success;
    ModbusException exception;
    uint8_t raw_exception;
};
 
class WriteHandler {
public:
    virtual ~WriteHandler() = default;
    
    virtual WriteResult write_single_coil(uint16_t index, bool value, Database& database) = 0;
    
    virtual WriteResult write_single_register(uint16_t index, uint16_t value, Database& database) = 0;
    
    virtual WriteResult write_multiple_coils(uint16_t start, BitValueIterator& it, Database& database) = 0;
    
    virtual WriteResult write_multiple_registers(uint16_t start, RegisterValueIterator& it, Database& database) = 0;
    
};
 
class DeviceMap;
 
class DeviceMap {
    friend class CppDeviceMapFriend;
    // pointer to the underlying C type
    void* self;
    // constructor only accessible internally
    DeviceMap(void* self): self(self) {}
    // non-copyable
    DeviceMap(const DeviceMap&) = delete;
    DeviceMap& operator=(const DeviceMap&) = delete;
    // no move assignment
    DeviceMap& operator=(DeviceMap&& other) = delete;
 
public:
    DeviceMap(DeviceMap&& other) noexcept : self(other.self) { other.self = nullptr; }
    
    DeviceMap();
    
    ~DeviceMap();
    
    bool add_endpoint(uint8_t unit_id, std::unique_ptr<WriteHandler> handler, DatabaseCallback& configure);
};
 
struct TlsServerConfig;
 
struct TlsServerConfig {
    friend class CppTlsServerConfigFriend;
    
private:
    TlsServerConfig(const std::string& peer_cert_path, const std::string& local_cert_path, const std::string& private_key_path, const std::string& password, MinTlsVersion min_tls_version, CertificateMode certificate_mode);
    
public:
    TlsServerConfig() = delete;
    
    TlsServerConfig(const std::string& peer_cert_path, const std::string& local_cert_path, const std::string& private_key_path, const std::string& password);
    
    
    std::string peer_cert_path;
    std::string local_cert_path;
    std::string private_key_path;
    std::string password;
    MinTlsVersion min_tls_version;
    CertificateMode certificate_mode;
};
 
enum class Authorization {
    allow = 0,
    deny = 1,
};
 
const char* to_string(Authorization value);
 
class AuthorizationHandler {
public:
    virtual ~AuthorizationHandler() = default;
    
    virtual Authorization read_coils(uint8_t unit_id, const AddressRange& range, const char* role) = 0;
    
    virtual Authorization read_discrete_inputs(uint8_t unit_id, const AddressRange& range, const char* role) = 0;
    
    virtual Authorization read_holding_registers(uint8_t unit_id, const AddressRange& range, const char* role) = 0;
    
    virtual Authorization read_input_registers(uint8_t unit_id, const AddressRange& range, const char* role) = 0;
    
    virtual Authorization write_single_coil(uint8_t unit_id, uint16_t index, const char* role) = 0;
    
    virtual Authorization write_single_register(uint8_t unit_id, uint16_t index, const char* role) = 0;
    
    virtual Authorization write_multiple_coils(uint8_t unit_id, const AddressRange& range, const char* role) = 0;
    
    virtual Authorization write_multiple_registers(uint8_t unit_id, const AddressRange& range, const char* role) = 0;
    
};
 
class AddressFilter;
 
class AddressFilter {
    friend class CppAddressFilterFriend;
    // pointer to the underlying C type
    void* self;
    // constructor only accessible internally
    AddressFilter(void* self): self(self) {}
    // non-copyable
    AddressFilter(const AddressFilter&) = delete;
    AddressFilter& operator=(const AddressFilter&) = delete;
    // no move assignment
    AddressFilter& operator=(AddressFilter&& other) = delete;
 
public:
    AddressFilter(AddressFilter&& other) noexcept : self(other.self) { other.self = nullptr; }
    
    AddressFilter(const std::string& address);
    
    ~AddressFilter();
    
    void add(const std::string& address);
    
    static AddressFilter any();
};
 
class Server;
 
class Server {
    friend class CppServerFriend;
    // pointer to the underlying C type
    void* self;
    // constructor only accessible internally
    Server(void* self): self(self) {}
    // non-copyable
    Server(const Server&) = delete;
    Server& operator=(const Server&) = delete;
    // no move assignment
    Server& operator=(Server&& other) = delete;
 
public:
    Server(Server&& other) noexcept : self(other.self) { other.self = nullptr; }
    
    ~Server();
    
    void update_database(uint8_t unit_id, DatabaseCallback& transaction);
    
    void set_decode_level(const DecodeLevel& level);
    
    static Server create_tcp(Runtime& runtime, const std::string& address, uint16_t port, AddressFilter& filter, uint16_t max_sessions, DeviceMap& endpoints, const DecodeLevel& decode_level);
    
    static Server create_rtu(Runtime& runtime, const std::string& path, const SerialPortSettings& serial_params, const RetryStrategy& retry, DeviceMap& endpoints, const DecodeLevel& decode_level);
    
    static Server create_tls_with_authz(Runtime& runtime, const std::string& address, uint16_t port, AddressFilter& filter, uint16_t max_sessions, DeviceMap& endpoints, const TlsServerConfig& tls_config, std::unique_ptr<AuthorizationHandler> authorization_handler, const DecodeLevel& decode_level);
    
    static Server create_tls(Runtime& runtime, const std::string& address, uint16_t port, AddressFilter& filter, uint16_t max_sessions, DeviceMap& endpoints, const TlsServerConfig& tls_config, const DecodeLevel& decode_level);
};
 
} // end namespace rodbus