device_parameter.h

Go to the documentation of this file.

#pragma once
 
#include <atomic>
#include <bit>
#include <cstdint>
#include <cstring>
#include <expected>
#include <format>
#include <nlohmann/json_fwd.hpp>
#include <optional>
#include <span>
#include <string>
#include <string_view>
#include <type_traits>
#include <variant>
#include <vector>
 
namespace mm::node {
 
// Values are stored and exchanged as little-endian wire bytes and read back by memcpy, here
// and in decodeSdoBytes. A big-endian host would need every one of those to byte-swap, so it
// must fail here rather than silently return reversed numbers.
static_assert(std::endian::native == std::endian::little,
              "parameter values are stored as little-endian wire bytes");
 
using DeviceParameterValue = std::variant<int8_t, int16_t, int32_t, int64_t,      //
                                          uint8_t, uint16_t, uint32_t, uint64_t,  //
                                          float, double,                          //
                                          std::string, std::vector<uint8_t>>;
 
constexpr uint32_t makeParameterKey(uint16_t index, uint8_t subindex) {
  return (static_cast<uint32_t>(index) << 8) | static_cast<uint32_t>(subindex);
}
 
template <typename T>
struct ObjectAddress {
  uint16_t index{};    
  uint8_t subindex{};  
};
 
DeviceParameterValue defaultValueForDataType(uint16_t dataType);
 
bool isScalarDataType(uint16_t dataType);
 
size_t scalarByteWidth(uint16_t dataType);
 
uint64_t packLeBits(std::span<const uint8_t> bytes);
 
void unpackLeBits(uint64_t bits, std::span<uint8_t> out);
 
std::optional<double> numericValue(const DeviceParameterValue& value);
 
enum class SyncState : uint8_t {
  Unknown,  
  Synced,   
  Pending,  
  Stale,    
};
 
std::string_view syncStateName(SyncState state);
 
enum class ParameterOrigin : uint8_t {
  ObjectDictionary,  
  Sii,               
};
 
std::string_view parameterOriginName(ParameterOrigin origin);
 
struct ScalarCell {
  mutable uint64_t value{0};
 
  ScalarCell() = default;
  ~ScalarCell() = default;
  ScalarCell(const ScalarCell& other) : value(other.load()) {}
  ScalarCell(ScalarCell&& other) noexcept : value(other.load()) {}
  ScalarCell& operator=(const ScalarCell& other) {
    if (this != &other) {
      store(other.load());
    }
    return *this;
  }
  ScalarCell& operator=(ScalarCell&& other) noexcept {
    store(other.load());
    return *this;
  }
 
  uint64_t load() const { return std::atomic_ref<uint64_t>(value).load(std::memory_order_relaxed); }
  void store(uint64_t v) const {
    std::atomic_ref<uint64_t>(value).store(v, std::memory_order_relaxed);
  }
 
  // The two properties the cell's whole contract rests on. Lock-freedom is what makes a read safe
  // from the RT loop at all; the alignment precondition is atomic_ref's, and a platform where a
  // uint64_t member does not satisfy it must fail here rather than degrade silently.
  static_assert(std::atomic_ref<uint64_t>::is_always_lock_free,
                "the parameter cell must be lock-free so the RT path never blocks");
  static_assert(alignof(uint64_t) >= std::atomic_ref<uint64_t>::required_alignment,
                "the parameter cell must satisfy std::atomic_ref's alignment requirement");
};
 
struct DeviceParameter {
  uint16_t index{};       
  uint8_t subindex{};     
  std::string name;       
  uint16_t objectCode{};  
  uint16_t dataType{};    
  uint16_t bitLength{};   
  uint16_t access{};      
  ParameterOrigin origin{ParameterOrigin::ObjectDictionary};  
 
  // --- value -------------------------------------------------------------------------------
  // The last-known value, stored as its raw little-endian wire bytes — the same encoding an SDO
  // transfer carries. @c isScalarDataType(dataType) picks which of the two fields holds it; zero
  // (an empty @c rawValue) is the type-appropriate default before the first read.
  //
  // A cyclic task reads the scalar through @c loadBits: one relaxed atomic load, no lock, no
  // allocation, and no way to tell whether the RT exchange or a background SDO poll put the value
  // there. Why that is a @c ScalarCell rather than a bare @c uint64_t is documented on the type.
  ScalarCell cell{};                
  std::vector<uint8_t> rawValue{};  
  SyncState syncState{SyncState::Unknown};  
  std::optional<uint32_t> unit;             
  std::optional<DeviceParameterValue> defaultValue;  
  std::optional<DeviceParameterValue> minValue;      
  std::optional<DeviceParameterValue> maxValue;      
 
  uint32_t key() const { return makeParameterKey(index, subindex); }
 
  uint64_t loadBits() const { return cell.load(); }
 
  void storeBits(uint64_t v) const { cell.store(v); }
 
  DeviceParameterValue currentValue() const;
 
  template <typename T>
  std::optional<T> scalar() const {
    static_assert(std::is_arithmetic_v<T>, "the cell holds arithmetic types only");
    static_assert(sizeof(T) <= sizeof(uint64_t), "the cell holds at most eight bytes");
    // Constructing the type's zero is how the alternative is named; for every scalar it is a
    // register-sized value, and for the string/bytes cases an empty container — no allocation
    // either way, so this stays RT-safe.
    if (!std::holds_alternative<T>(defaultValueForDataType(dataType))) {
      return std::nullopt;
    }
    const uint64_t v = loadBits();
    T out{};
    std::memcpy(&out, &v, sizeof(T));
    return out;
  }
 
  std::vector<uint8_t> rawValueBytes() const;
 
  void setRawValue(std::span<const uint8_t> bytes);
 
  void markReadFailed() {
    if (syncState == SyncState::Synced) {
      syncState = SyncState::Stale;
    }
  }
 
  template <typename T>
  std::expected<T, std::string> getValue() const {
    const DeviceParameterValue v = currentValue();
    if (const auto* p = std::get_if<T>(&v)) {
      return *p;
    }
    return std::unexpected(
        std::format("parameter 0x{:04X}:{:02X} holds a different type", index, subindex));
  }
 
  std::expected<double, std::string> numeric() const;
 
  std::expected<std::vector<uint8_t>, std::string> encode(const DeviceParameterValue& v) const;
 
  std::expected<void, std::string> setValue(const DeviceParameterValue& v);
 
  template <typename T>
  std::expected<void, std::string> setValue(const T& v) {
    return setValue(DeviceParameterValue{v});
  }
 
  bool isReadable() const { return (access & 0x07) != 0; }
};
 
std::expected<DeviceParameterValue, std::string> decodeSdoBytes(uint16_t dataType,
                                                                std::span<const uint8_t> bytes);
 
std::expected<std::vector<uint8_t>, std::string> encodeSdoBytes(uint16_t dataType,
                                                                const DeviceParameterValue& value);
 
void to_json(nlohmann::json& j, const DeviceParameter& p);
 
}  // namespace mm::node