irrigation_system/software/include/lib/modbus_server.h

#ifndef MODBUS_SERVER_H
#define MODBUS_SERVER_H

#include <stdint.h>

/**
 * @file modbus_server.h
 * @brief API for the Modbus server implementation.
 *
 * This file defines the Modbus register map and provides functions to
 * initialize and manage the Modbus server.
 */

/**
 * @brief Modbus Input Register Addresses (Read-Only).
 * @see docs/modbus-registers.de.md
 */
enum {
  /**
   * @brief Kombiniertes Status-Register für das Ventil.
   * High-Byte: Bewegung (0=Idle, 1=Öffnet, 2=Schliesst, 3=Fehler).
   * Low-Byte: Zustand (0=Geschlossen, 1=Geöffnet).
   */
  REG_INPUT_VALVE_STATE_MOVEMENT = 0x0000,
  /**
   * @brief Motorstrom beim Öffnen in Milliampere (mA) - IN0 current sense.
   */
  REG_INPUT_MOTOR_OPEN_CURRENT_MA = 0x0001,
  /**
   * @brief Motorstrom beim Schließen in Milliampere (mA) - IN1 current sense.
   */
  REG_INPUT_MOTOR_CLOSE_CURRENT_MA = 0x0002,
  /**
   * @brief Bitmaske der digitalen Eingänge. Bit 0: Eingang 1, Bit 1: Eingang 2.
   * 1=Aktiv.
   */
  REG_INPUT_DIGITAL_INPUTS_STATE = 0x0020,
  /**
   * @brief Event-Flags für Taster (Clear-on-Read). Bit 0: Taster 1 gedrückt.
   * Bit 1: Taster 2 gedrückt.
   */
  REG_INPUT_BUTTON_EVENTS = 0x0021,
  /**
   * @brief Firmware-Version, z.B. 0x0102 für v1.2.
   */
  REG_INPUT_FIRMWARE_VERSION_MAJOR_MINOR = 0x00F0,
  /**
   * @brief Firmware-Version Patch-Level, z.B. 3 für v1.2.3.
   */
  REG_INPUT_FIRMWARE_VERSION_PATCH = 0x00F1,
  /**
   * @brief Gerätestatus (0=OK, 1=Allgemeiner Fehler).
   */
  REG_INPUT_DEVICE_STATUS = 0x00F2,
  /**
   * @brief Untere 16 Bit der Uptime in Sekunden.
   */
  REG_INPUT_UPTIME_SECONDS_LOW = 0x00F3,
  /**
   * @brief Obere 16 Bit der Uptime in Sekunden.
   */
  REG_INPUT_UPTIME_SECONDS_HIGH = 0x00F4,
  /**
   * @brief Aktuelle Versorgungsspannung in Millivolt (mV).
   */
  REG_INPUT_SUPPLY_VOLTAGE_MV = 0x00F5,
  /**
   * @brief CRC16 des zuletzt im Puffer empfangenen Daten-Chunks für das
   * Firmware-Update.
   */
  REG_INPUT_FWU_LAST_CHUNK_CRC = 0x0100
};

/**
 * @brief Modbus Holding Register Addresses (Read/Write).
 * @see docs/modbus-registers.de.md
 */
enum {
  /**
   * @brief Ventilsteuerungsbefehl (1=Öffnen, 2=Schliessen, 0=Bewegung stoppen).
   */
  REG_HOLDING_VALVE_COMMAND = 0x0000,
  /**
   * @brief Sicherheits-Timeout in Sekunden für den Öffnen-Vorgang.
   */
  REG_HOLDING_MAX_OPENING_TIME_S = 0x0001,
  /**
   * @brief Sicherheits-Timeout in Sekunden für den Schliessen-Vorgang.
   */
  REG_HOLDING_MAX_CLOSING_TIME_S = 0x0002,
  /**
   * @brief Bitmaske zum Lesen und Schreiben der digitalen Ausgänge. Bit 0:
   * Ausgang 1, Bit 1: Ausgang 2. 1=AN, 0=AUS.
   */
  REG_HOLDING_DIGITAL_OUTPUTS_STATE = 0x0010,
  /**
   * @brief Timeout des Fail-Safe-Watchdogs in Sekunden. 0=Deaktiviert.
   */
  REG_HOLDING_WATCHDOG_TIMEOUT_S = 0x00F0,
  /**
   * @brief Schreiben von 1 startet das Gerät neu.
   */
  REG_HOLDING_DEVICE_RESET = 0x00F1,
  /**
   * @brief Befehl für das Firmware-Update.
   * 1: Verify Chunk - Slave schreibt den letzten Chunk ins Flash.
   * 2: Finalize Update - Installation abschliessen und neu starten.
   */
  REG_HOLDING_FWU_COMMAND = 0x0100,
  /**
   * @brief Untere 16 Bit des 32-Bit-Offsets für den nächsten
   * Firmware-Update-Chunk.
   */
  REG_HOLDING_FWU_CHUNK_OFFSET_LOW = 0x0101,
  /**
   * @brief Obere 16 Bit des 32-Bit-Offsets für den nächsten
   * Firmware-Update-Chunk.
   */
  REG_HOLDING_FWU_CHUNK_OFFSET_HIGH = 0x0102,
  /**
   * @brief Grösse des nächsten Firmware-Update-Chunks in Bytes (max. 256).
   */
  REG_HOLDING_FWU_CHUNK_SIZE = 0x0103,
  /**
   * @brief Startadresse des 256-Byte-Puffers für Firmware-Update-Daten.
   */
  REG_HOLDING_FWU_DATA_BUFFER = 0x0180,
};

/**
 * @brief Initializes the Modbus server.
 *
 * This function sets up the Modbus RTU server interface, loads saved settings
 * (baudrate, unit ID), and starts listening for requests.
 *
 * @return 0 on success, or a negative error code on failure.
 */
int modbus_server_init(void);

/**
 * @brief Reconfigures the Modbus server at runtime.
 *
 * Updates the baudrate and unit ID of the server. If the reconfiguration
 * fails, the settings are saved and will be applied after a device reset.
 *
 * @param baudrate The new baudrate to set.
 * @param unit_id The new Modbus unit ID (slave address).
 * @return 0 on success, or a negative error code if immediate reconfiguration
 * fails. Returns 0 even on failure if settings could be saved for the next
 * boot.
 */
int modbus_reconfigure(uint32_t baudrate, uint8_t unit_id);

/**
 * @brief Gets the current baudrate of the Modbus server.
 *
 * @return The current baudrate.
 */
uint32_t modbus_get_baudrate(void);

/**
 * @brief Gets the current unit ID of the Modbus server.
 *
 * @return The current unit ID.
 */
uint8_t modbus_get_unit_id(void);

#endif  // MODBUS_SERVER_H