Skip to content

Porting

How to write the port class that connects the driver to your MCU's UART, clock and pins.

Datasheet sections this page relies on
  • UART framing, echo and terminator: PyroScience Datasheet_FDO2-G2 v5, 4.1 General Definitions, p. 10
  • BAUD: the eleven baud rates: PyroScience Datasheet_FDO2-G2 v5, 4.3 Commands, #BAUD, p. 14

  • Connector, pins and signal levels: PyroScience Datasheet_FDO2-G2 v5, 7 Mechanical Dimensions and Electrical Interface, drawing and pin table, p. 20
  • UART levels: 3.0 V, 3.3 V maximum on RXD: PyroScience Datasheet_FDO2 v21, 6.2 Voltage Tolerance of UART RX Pin (ERRATA), p. 19

All of them, with the driver API for each: Datasheet map.

The driver never calls your SDK. It calls hooks on a class you derive from fdo2::UartInterface<Self> (in inc/fdo2_uart_interface.hpp). The base uses CRTP and declares no hook itself; the driver template is constrained by the fdo2::UartPort concept, which checks each hook's exact signature and noexcept. A missing or misdeclared hook is a compile error at the point of use.

What you implement

Method Required Contract
bool EnsureInitialized() noexcept yes Bring the UART up on the first call, 19200 8N1; return true at once afterwards
bool Write(const uint8_t* data, std::size_t len) noexcept yes Send all len bytes; false on an error
std::size_t Read(uint8_t* data, std::size_t max, uint32_t timeout_ms) noexcept yes Return the bytes received, 0 to max, waiting up to timeout_ms for the first one
bool FlushInput() noexcept yes Drop every received byte not yet returned by Read()
void DelayUs(uint32_t us) noexcept for the blocking calls Wait at least us microseconds
uint32_t NowUs() noexcept no A free-running microsecond counter, wrap-safe; Poll() then takes no argument
bool SetBaudRate(uint32_t baud) noexcept no Reconfigure the UART; without it SetBaudRate() returns Unsupported
bool GpioSet(CtrlPin, GpioSignal) noexcept no CtrlPin::Power: ACTIVE powers the module (an external load switch)
void Log(LogLevel, const char*) noexcept no Print one line; the message is plain text, never a format string
my_port.hpp
class MyPort : public fdo2::UartInterface<MyPort> {
public:
  // Bring the UART up once; later calls return true at once.
  bool EnsureInitialized() noexcept {
    if (!ready_) {
      ready_ = platform_uart_init();
    }
    return ready_;
  }

  bool Write(const uint8_t* data, std::size_t len) noexcept {
    return platform_uart_write(data, len);
  }

  // The number of bytes read (0 to `max`), waiting up to `timeout_ms` for the first one.
  // The reply length is not known in advance, so this is not an exact-length read.
  std::size_t Read(uint8_t* data, std::size_t max, uint32_t timeout_ms) noexcept {
    return platform_uart_read(data, max, timeout_ms);
  }

  // Drop stale bytes before each request.
  bool FlushInput() noexcept {
    return platform_uart_flush_input();
  }

  // Wait at least `us` microseconds: the module's processing times depend on it.
  void DelayUs(uint32_t us) noexcept {
    platform_delay_us(us);
  }

private:
  bool ready_ = false;
};

Rules

  • Raw bytes only. The driver builds the lines and checks the checksum; the port does not parse or retry.
  • Read() returns a count. The reply length is not known in advance, so it is not an exact-length read. It waits for the first byte up to timeout_ms and returns what is in the FIFO. A port whose SDK returns only a status polls the FIFO level first.
  • The receive buffer holds at least 800 bytes (kRxBufferBytes): the longest reply. A smaller buffer loses bytes while the driver is busy with something else.
  • FlushInput() really flushes. The driver calls it before each request so a stale byte cannot shift a reply.
  • 19200 baud, 8N1, no flow control at start; the module starts there after every power-up.
  • Without NowUs, call Poll(elapsed_us); with it, Poll() (Non-blocking use).
  • A hook that returns false is reported as Bus.
  • DelayUs should yield for a millisecond or more on an RTOS (the ESP32 port calls vTaskDelay), so the other tasks run during the 1.5 s power-up wait.
  • Loopback. A TX line wired to RX echoes every command. The driver does not take an echo of its own #VERS as an answer: the identity must match, so the start-up fails with DeviceIdMismatch or InvalidReply.
  • No power pin. A port whose power pin is not fitted returns true from GpioSet for CtrlPin::Power, a valid no-op (the ESP32 example does so for pin -1).

Idle level of the supply switch: INACTIVE (module off) before the output is enabled and before the first line is sent; the port maps ACTIVE to the polarity of your switch.

Bus requirements

The driver states what the module needs as constexpr values; check your port against them with static_assert, as both example ports do:

ports.cpp
// The line the port must provide, checked at build time.
static_assert(fdo2::kPortDefaultBaud == 19'200U, "8N1 at 19200 baud");
static_assert(fdo2::kRxBufferBytes >= 800U, "a reply can be 800 characters");
Constant Value Meaning
kPortDefaultBaud 19200 The rate after every power-up
kLogicLevelMv 3000 The module's signal level
kMaxLogicLevelMv 3300 Absolute maximum on RXD
kSupplyMinMv, kSupplyMaxMv 3300, 5000 The supply range
kPowerUpMs 1000 The module's power-up time
kRxBufferBytes 800 The longest reply

A port with every hook

ports.cpp
class FullPort : public fdo2::UartInterface<FullPort> {
public:
  // Required hooks.
  bool EnsureInitialized() noexcept {
    return platform_uart_init();
  }
  bool Write(const uint8_t* data, std::size_t len) noexcept {
    return platform_uart_write(data, len);
  }
  std::size_t Read(uint8_t* data, std::size_t max, uint32_t timeout_ms) noexcept {
    return platform_uart_read(data, max, timeout_ms);
  }
  bool FlushInput() noexcept {
    return platform_uart_flush_input();
  }

  // Optional hooks: each enables part of the API.
  void DelayUs(uint32_t us) noexcept { // the blocking calls and PowerCycle()
    platform_delay_us(us);
  }
  uint32_t NowUs() noexcept { // Poll() without an argument
    return platform_now_us();
  }
  bool SetBaudRate(uint32_t baud) noexcept { // SetBaudRate()
    return platform_uart_set_baud(baud);
  }
  bool GpioSet(fdo2::CtrlPin pin, fdo2::GpioSignal level) noexcept { // the power pin
    (void)pin;
    return platform_gpio_write(7, level == fdo2::GpioSignal::ACTIVE);
  }
  void Log(fdo2::LogLevel level, const char* message) noexcept {
    (void)level;
    platform_log(message);
  }
};

The ESP-IDF port and the host port are complete examples.