Motion Master 6.0.0-alpha.50
Next-generation motion control software
Loading...
Searching...
No Matches
mm::node Namespace Reference

Namespaces

namespace  cia402
 

Classes

class  Cia402Drive
 Borrowed view of a CiA402 drive — the device control state machine, operation modes, and the standard cyclic setpoints, expressed over a Device's parameter access. More...
 
struct  DcSyncInfo
 A slave's live distributed-clock sync status plus its resolved device name. More...
 
class  Device
 Represents a single node on the fieldbus. More...
 
struct  DeviceDiagnosticsInfo
 A slave's live ESC health diagnostics plus its resolved device name. More...
 
class  DeviceManager
 Owns the fieldbus driver and node collection, and drives PDO exchange. More...
 
struct  DeviceManagerConfig
 Runtime tuning passed to DeviceManager::init. Every field has a sensible default, so a caller can pass {} (or omit it) and override only what it cares about; new knobs can be added here without changing the init signature. More...
 
struct  DeviceParameter
 A single object dictionary entry held by a Device. More...
 
struct  DeviceStateInfo
 Current AL state snapshot for a single device. More...
 
struct  DumpDevice
 One device's identity and the PDO objects it contributes to the image. More...
 
struct  DumpHeader
 The embedded process-image header: everything needed to decode the rows offline. More...
 
struct  DumpPdoEntry
 One PDO-mapped object as recorded in the dump header. More...
 
struct  FlatPdoMapping
 A device's complete PDO mapping across both directions. More...
 
struct  MonitoredParameter
 One object a monitoring samples, addressed by bus position and CoE index. More...
 
struct  Monitoring
 A client-defined recording of a set of parameters streamed over time. More...
 
class  MonitoringManager
 Owns the active monitorings and turns each into a lossless stream of recorded rows. More...
 
struct  OutputStageRequest
 One object to stage into the output process image, as parsed from a batch write request. More...
 
struct  OutputStageResult
 Per-object outcome of a batch output stage. More...
 
class  ParameterCache
 On-disk cache of CoE parameter definitions, keyed by device identity. More...
 
struct  ParameterCacheConfig
 Policy and location for the on-disk parameter cache. More...
 
class  ParameterRefresher
 Keeps a reference-counted set of SDO parameters fresh by polling them off-thread. More...
 
struct  PdoMapping
 A device's desired PDO configuration to write and assign — the write-side input to Device::writePdoMapping, and the grouped counterpart of the read-side FlatPdoMapping. More...
 
struct  PdoMappingEntry
 One object mapped into a slave's process data, with its position in the window. More...
 
struct  PdoMappingObject
 One PDO mapping object (0x16xx RxPDO / 0x1Axx TxPDO) and its ordered entries. More...
 
struct  ProcessBuffer
 Fixed-capacity byte buffer for one direction of the process image. More...
 
struct  ProcessData
 The live process-data runtime: the published image, the cross-thread exchange buffers, and per-object PDO access over them. More...
 
class  ProcessDataRing
 A lock-free circular recorder of the raw process image, one record per RT cycle. More...
 
struct  ProcessImage
 The whole bus's process-data layout, resolved to absolute positions. More...
 
struct  ProcessImageEntry
 Locates one mapped object within the flat process image. More...
 
struct  ProcessImageInfo
 API-facing snapshot of the currently published process image and its runtime health. More...
 
struct  ProcessImageObjectInfo
 One mapped object in the published process image, with its name resolved. More...
 
class  ProfileDevice
 Base of the drive-profile view hierarchy: a thin, borrowed view over a Device. More...
 
struct  SlaveConfigInfo
 A slave's static ESC configuration plus its resolved device name. More...
 
class  SomanetDrive
 Borrowed view of a SOMANET drive — a CiA402 drive plus Synapticon-specific object-dictionary access (encoder/motor configuration, commutation offset, etc.). More...
 

Typedefs

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 > >
 Decoded value of a single device parameter (CoE object dictionary entry).
 
using DumpRecordReader = std::function< bool(uint64_t seq, ProcessDataRing::Record &out)>
 Reads the record for seq into out; returns false if it is no longer available (lapped or a torn read). Wraps ProcessDataRing::readRecord.
 

Enumerations

enum class  SyncState : uint8_t { Unknown , Synced , Pending }
 Tracks how a cached parameter value relates to the device. More...
 

Functions

std::expected< Cia402Drive, std::string > createCia402Drive (Device &device)
 Validates that device implements the CiA402 profile, then binds a view to it.
 
void to_json (nlohmann::json &j, const Device &d)
 Serialises a Device to JSON.
 
std::expected< int, std::string > reconcileDetectedModules (const Device &device)
 Reconciles a device's Configured Module Ident List with its Detected list.
 
void to_json (nlohmann::json &j, const DeviceStateInfo &info)
 Serialises a DeviceStateInfo to JSON.
 
void to_json (nlohmann::json &j, const OutputStageResult &result)
 Serialises an OutputStageResult to JSON.
 
void to_json (nlohmann::json &j, const ProcessImageObjectInfo &obj)
 Serialises a ProcessImageObjectInfo to JSON.
 
void to_json (nlohmann::json &j, const ProcessImageInfo &info)
 Serialises a ProcessImageInfo to JSON.
 
void to_json (nlohmann::json &j, const SlaveConfigInfo &info)
 Serialises a SlaveConfigInfo (and its nested SM/FMMU/mailbox/DC) to JSON.
 
void to_json (nlohmann::json &j, const DeviceDiagnosticsInfo &info)
 Serialises a DeviceDiagnosticsInfo (and its nested per-port counters) to JSON.
 
void to_json (nlohmann::json &j, const DcSyncInfo &info)
 Serialises a DcSyncInfo to JSON.
 
void to_json (nlohmann::json &j, const DeviceManager &dm)
 Serialises all devices in a DeviceManager to a JSON array.
 
DeviceParameterValue defaultValueForDataType (uint16_t dataType)
 Returns a zero-equivalent value for the given ETG.1020 dataType.
 
std::expected< DeviceParameterValue, std::string > decodeSdoBytes (uint16_t dataType, std::span< const uint8_t > bytes)
 Decodes a raw SDO byte sequence according to an ETG.1020 data type code.
 
std::expected< std::vector< uint8_t >, std::string > encodeSdoBytes (uint16_t dataType, const DeviceParameterValue &value)
 Serialises a DeviceParameterValue to raw SDO bytes — the inverse of decodeSdoBytes.
 
std::optional< double > numericValue (const DeviceParameterValue &value)
 Coerces a DeviceParameterValue to a double, when it holds a number.
 
std::string_view syncStateName (SyncState state)
 Returns the lowercase string form of state ("unknown" etc.).
 
void to_json (nlohmann::json &j, const DeviceParameter &p)
 Serialises a DeviceParameter to JSON.
 
constexpr uint32_t makeParameterKey (uint16_t index, uint8_t subindex)
 Packs an object dictionary index and subindex into a single 32-bit key.
 
void to_json (nlohmann::json &j, const MonitoredParameter &p)
 Serialises a MonitoredParameter to JSON: {devicePosition, index, subindex}.
 
void to_json (nlohmann::json &j, const Monitoring &m)
 Serialises a Monitoring to JSON: {topic, name?, interval, parameters}.
 
void to_json (nlohmann::json &j, const ParameterCache::CacheEntry &e)
 Serialises a CacheEntry to JSON (keys: vendorId, productCode, revisionNumber, parameterCount, sizeBytes). Participates in nlohmann ADL.
 
void to_json (nlohmann::json &j, const PdoMappingEntry &e)
 Serialises a single entry: index, subindex, bitLength, bitOffset.
 
void to_json (nlohmann::json &j, const PdoMappingObject &o)
 Serialises one mapping object: pdoIndex and its ordered entries.
 
void to_json (nlohmann::json &j, const PdoMapping &m)
 Serialises a device's grouped mapping: outputs / inputs object arrays. The response shape of the PDO-mapping routes (each entry carries its derived bitOffset).
 
uint32_t packMappingEntry (const PdoMappingEntry &e)
 Packs an entry into its 32-bit CoE mapping word (ETG.1000.6 §5.6.7.4.7): index<<16 | subindex<<8 | bitLength.
 
PdoMappingEntry unpackMappingEntry (uint32_t packed)
 Unpacks a 32-bit CoE mapping word into an entry — the inverse of packMappingEntry.
 
std::expected< uint64_t, std::string > writeProcessDataDump (std::ostream &out, const DumpHeader &header, uint64_t startSeq, uint64_t endSeq, const DumpRecordReader &read)
 Serialises the frozen span [startSeq, endSeq) to out as a .mmpd dump.
 
std::expected< ProcessImage, std::string > buildProcessImage (const mm::comm::PdoLayout &layout, const std::vector< Device > &devices)
 Assembles a ProcessImage from the driver layout and per-device PDO mappings.
 
std::vector< uint8_t > extractBits (std::span< const uint8_t > src, uint32_t bitOffset, uint16_t bitLength)
 Extracts bitLength bits at bitOffset from src into a fresh LSB-aligned little-endian byte vector (ceil(bitLength/8) bytes), as the SDO encoding would.
 
void insertBits (std::span< uint8_t > dst, uint32_t bitOffset, uint16_t bitLength, std::span< const uint8_t > value)
 Inserts bitLength bits of value (LSB-first) into dst at bitOffset.
 
std::expected< SomanetDrive, std::string > createSomanetDrive (Device &device)
 Validates that device is a SOMANET drive, then binds a view to it.
 

Variables

constexpr uint32_t kSynapticonVendorId = 0x000022D2
 EtherCAT vendor ID of Synapticon (SOMANET drives).
 
constexpr std::array< char, 4 > kDumpMagic = {'M', 'M', 'P', 'D'}
 Magic at the very start of every dump file.
 
constexpr uint16_t kDumpFormatVersion = 1
 Current dump format version. A reader rejects an unknown major shape; bump on layout changes so old files stay identifiable.
 
constexpr std::streamoff kDumpRowCountOffset = 16
 Byte offset of the rowCount field within the fixed prefix. The writer streams rows first, then seeks here to patch the final count — so the stream must be seekable.
 

Typedef Documentation

◆ DeviceParameterValue

using mm::node::DeviceParameterValue = typedef 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> >

Decoded value of a single device parameter (CoE object dictionary entry).

The variant alternatives cover the standard ETG.1020 data types that can be transferred via SDO upload. Use std::visit to dispatch on the active type.

◆ DumpRecordReader

using mm::node::DumpRecordReader = typedef std::function<bool(uint64_t seq, ProcessDataRing::Record& out)>

Reads the record for seq into out; returns false if it is no longer available (lapped or a torn read). Wraps ProcessDataRing::readRecord.

Enumeration Type Documentation

◆ SyncState

enum class mm::node::SyncState : uint8_t
strong

Tracks how a cached parameter value relates to the device.

A device may be edited while offline (powered off, or in INIT with no mailbox); this flag lets callers tell a freshly-read value from a stale or pending one (see NEXTGEN.md — "tag offline values with a freshness flag").

Enumerator
Unknown 

Never read; value is the type-appropriate default.

Synced 

value matches the device (last successful read or write).

Pending 

value was set locally while offline / after a failed write.

Function Documentation

◆ buildProcessImage()

std::expected< ProcessImage, std::string > mm::node::buildProcessImage ( const mm::comm::PdoLayout layout,
const std::vector< Device > &  devices 
)

Assembles a ProcessImage from the driver layout and per-device PDO mappings.

Matches each device to its window in layout by bus position and combines the window offset with the device's per-object bit offsets to produce absolute positions. Padding entries (index == 0) are dropped — they bind to no object. Devices must have had Device::readFlatPdoMapping called already.

Parameters
layoutPer-slave windows and image sizes from FieldbusDriver::processDataLayout.
devicesDevices whose flatPdoMapping() supply the per-object offsets.
Returns
The assembled image, or an error string if a device has a mapping but no matching window in layout, or its mapped width overflows the window the driver reserved.

◆ createCia402Drive()

std::expected< Cia402Drive, std::string > mm::node::createCia402Drive ( Device device)

Validates that device implements the CiA402 profile, then binds a view to it.

The check is offline-safe: it requires the controlword (0x6040) and statusword (0x6041) objects to be present in the device's parameter map (populated by Device::initializeParameters). No bus I/O is performed.

Parameters
deviceDevice to view. The reference must outlive the returned view.
Returns
A Cia402Drive bound to device, or an error string if it is not a CiA402 drive (or its parameters have not been initialised).

◆ createSomanetDrive()

std::expected< SomanetDrive, std::string > mm::node::createSomanetDrive ( Device device)

Validates that device is a SOMANET drive, then binds a view to it.

Requires the vendor ID to be Synapticon's (kSynapticonVendorId) and the device to satisfy the CiA402 check (createCia402Drive). Both are offline-safe — vendor ID is immutable identity read at scan, the CiA402 check reads the parameter map — so no bus I/O is performed.

Parameters
deviceDevice to view. The reference must outlive the returned view.
Returns
A SomanetDrive bound to device, or an error string if it is not a SOMANET drive.

◆ decodeSdoBytes()

std::expected< DeviceParameterValue, std::string > mm::node::decodeSdoBytes ( uint16_t  dataType,
std::span< const uint8_t >  bytes 
)

Decodes a raw SDO byte sequence according to an ETG.1020 data type code.

Parameters
dataTypeETG.1020 data type code (e.g. 0x0007 = UNSIGNED32).
bytesBytes returned by an SDO upload.
Returns
The decoded value on success, or an error string if dataType is unsupported or bytes is too short for the type.

◆ defaultValueForDataType()

DeviceParameterValue mm::node::defaultValueForDataType ( uint16_t  dataType)

Returns a zero-equivalent value for the given ETG.1020 dataType.

Used to initialise DeviceParameter::value so the active variant alternative matches the parameter's declared type before the first read. Unknown data types fall back to std::vector<uint8_t>{}.

◆ encodeSdoBytes()

std::expected< std::vector< uint8_t >, std::string > mm::node::encodeSdoBytes ( uint16_t  dataType,
const DeviceParameterValue value 
)

Serialises a DeviceParameterValue to raw SDO bytes — the inverse of decodeSdoBytes.

The active variant alternative must match dataType (numeric types expect the scalar of the corresponding width; string types expect std::string). Strings are written as their raw bytes with no trailing NUL so that decodeSdoBytes(t, encodeSdoBytes(t, v)) round-trips exactly. Unknown / composite types expect a std::vector<uint8_t> and are copied verbatim.

Parameters
dataTypeETG.1020 data type code.
valueValue to serialise.
Returns
The encoded bytes on success, or an error string if value's alternative does not match dataType.

◆ extractBits()

std::vector< uint8_t > mm::node::extractBits ( std::span< const uint8_t >  src,
uint32_t  bitOffset,
uint16_t  bitLength 
)

Extracts bitLength bits at bitOffset from src into a fresh LSB-aligned little-endian byte vector (ceil(bitLength/8) bytes), as the SDO encoding would.

Byte-aligned extents are a plain copy; sub-byte extents are assembled bit by bit.

◆ insertBits()

void mm::node::insertBits ( std::span< uint8_t >  dst,
uint32_t  bitOffset,
uint16_t  bitLength,
std::span< const uint8_t >  value 
)

Inserts bitLength bits of value (LSB-first) into dst at bitOffset.

The inverse of extractBits. Bits of value beyond what it provides are treated as 0.

◆ makeParameterKey()

constexpr uint32_t mm::node::makeParameterKey ( uint16_t  index,
uint8_t  subindex 
)
constexpr

Packs an object dictionary index and subindex into a single 32-bit key.

Layout: (index << 8) | subindex. Used as the key of Device::parameters().

◆ numericValue()

std::optional< double > mm::node::numericValue ( const DeviceParameterValue value)

Coerces a DeviceParameterValue to a double, when it holds a number.

Returns
The value as a double for any arithmetic alternative, or std::nullopt for std::string / std::vector<uint8_t>.

◆ packMappingEntry()

uint32_t mm::node::packMappingEntry ( const PdoMappingEntry e)
inline

Packs an entry into its 32-bit CoE mapping word (ETG.1000.6 §5.6.7.4.7): index<<16 | subindex<<8 | bitLength.

bitOffset is not part of the wire word — it is derived from the running offset by the reader. This is the word Device::writePdoMapping writes to each mapping-object subindex.

◆ reconcileDetectedModules()

std::expected< int, std::string > mm::node::reconcileDetectedModules ( const Device device)

Reconciles a device's Configured Module Ident List with its Detected list.

Walks the EtherCAT Modular Device Profile objects (ETG.5001): for every populated slot in the Detected Module Ident List (0xF050) it writes the detected ident into the matching subindex of the Configured Module Ident List (0xF030). A drive whose configured and detected lists disagree reports a module mismatch and refuses to leave PRE-OP; copying detected into configured clears it.

The device must be in PRE-OP or higher (SDO mailbox active) — 0xF030 is writable in PRE-OP. Vendor-neutral: keyed only on the standard MDP objects, never on vendor ID. Best-effort and idempotent: a device that does not implement 0xF050 (i.e. is not modular) is treated as success with zero slots written, and slots whose configured entry already matches the detected one are left untouched.

Parameters
deviceTarget device; must have mailbox communication active (PRE-OP+).
Returns
The number of configured-list subindices written, or an error string naming the slot(s) whose write to 0xF030 failed.

◆ syncStateName()

std::string_view mm::node::syncStateName ( SyncState  state)

Returns the lowercase string form of state ("unknown" etc.).

◆ to_json() [1/16]

void mm::node::to_json ( nlohmann::json &  j,
const DcSyncInfo info 
)

Serialises a DcSyncInfo to JSON.

◆ to_json() [2/16]

void mm::node::to_json ( nlohmann::json &  j,
const Device d 
)

Serialises a Device to JSON.

Produces an object with keys slavePosition, name, vendorId, productCode, revisionNumber, and serialNumber. Participates in nlohmann ADL so that nlohmann::json(device) and std::vector<Device> conversions work automatically.

Parameters
jOutput JSON value.
dDevice to serialise.

◆ to_json() [3/16]

void mm::node::to_json ( nlohmann::json &  j,
const DeviceDiagnosticsInfo info 
)

Serialises a DeviceDiagnosticsInfo (and its nested per-port counters) to JSON.

◆ to_json() [4/16]

void mm::node::to_json ( nlohmann::json &  j,
const DeviceManager dm 
)

Serialises all devices in a DeviceManager to a JSON array.

Produces a JSON array where each element is the serialised form of a Device (see to_json(nlohmann::json&, const Device&)), in bus order. Participates in nlohmann ADL so that nlohmann::json(deviceManager) works.

Parameters
jOutput JSON value.
dmDeviceManager whose device list to serialise.

◆ to_json() [5/16]

void mm::node::to_json ( nlohmann::json &  j,
const DeviceParameter p 
)

Serialises a DeviceParameter to JSON.

Produces an object with keys index, subindex, name, objectCode, dataType, bitLength, access, and value.

◆ to_json() [6/16]

void mm::node::to_json ( nlohmann::json &  j,
const DeviceStateInfo info 
)

Serialises a DeviceStateInfo to JSON.

◆ to_json() [7/16]

void mm::node::to_json ( nlohmann::json &  j,
const MonitoredParameter p 
)

Serialises a MonitoredParameter to JSON: {devicePosition, index, subindex}.

◆ to_json() [8/16]

void mm::node::to_json ( nlohmann::json &  j,
const Monitoring m 
)

Serialises a Monitoring to JSON: {topic, name?, interval, parameters}.

name is omitted when unset; interval is emitted as an integer count of milliseconds.

◆ to_json() [9/16]

void mm::node::to_json ( nlohmann::json &  j,
const OutputStageResult result 
)

Serialises an OutputStageResult to JSON.

◆ to_json() [10/16]

void mm::node::to_json ( nlohmann::json &  j,
const ParameterCache::CacheEntry e 
)

Serialises a CacheEntry to JSON (keys: vendorId, productCode, revisionNumber, parameterCount, sizeBytes). Participates in nlohmann ADL.

◆ to_json() [11/16]

void mm::node::to_json ( nlohmann::json &  j,
const PdoMapping m 
)

Serialises a device's grouped mapping: outputs / inputs object arrays. The response shape of the PDO-mapping routes (each entry carries its derived bitOffset).

◆ to_json() [12/16]

void mm::node::to_json ( nlohmann::json &  j,
const PdoMappingEntry e 
)

Serialises a single entry: index, subindex, bitLength, bitOffset.

◆ to_json() [13/16]

void mm::node::to_json ( nlohmann::json &  j,
const PdoMappingObject o 
)

Serialises one mapping object: pdoIndex and its ordered entries.

◆ to_json() [14/16]

void mm::node::to_json ( nlohmann::json &  j,
const ProcessImageInfo info 
)

Serialises a ProcessImageInfo to JSON.

◆ to_json() [15/16]

void mm::node::to_json ( nlohmann::json &  j,
const ProcessImageObjectInfo obj 
)

Serialises a ProcessImageObjectInfo to JSON.

◆ to_json() [16/16]

void mm::node::to_json ( nlohmann::json &  j,
const SlaveConfigInfo info 
)

Serialises a SlaveConfigInfo (and its nested SM/FMMU/mailbox/DC) to JSON.

◆ unpackMappingEntry()

PdoMappingEntry mm::node::unpackMappingEntry ( uint32_t  packed)
inline

Unpacks a 32-bit CoE mapping word into an entry — the inverse of packMappingEntry.

The returned entry's bitOffset is left at its default; the reader fills it from the running offset. An index of 0x0000 denotes an alignment gap (no bound object).

◆ writeProcessDataDump()

std::expected< uint64_t, std::string > mm::node::writeProcessDataDump ( std::ostream &  out,
const DumpHeader header,
uint64_t  startSeq,
uint64_t  endSeq,
const DumpRecordReader read 
)

Serialises the frozen span [startSeq, endSeq) to out as a .mmpd dump.

Streams each row directly from read (no whole-span buffer), padding/truncating its input/output regions to the header sizes for a fixed stride. A record read cannot return (lapped while the producer is still running, or a torn read) is skipped — every row carries its own sequence, so a gap is self-describing and needs no marker; at a seconds-deep ring versus a sub-second bulk write this never actually happens. rowCount is patched at kDumpRowCountOffset once the real count is known, so out must be seekable (a file or string stream).

Returns
The number of rows written, or an error string if a stream write/seek failed.

Variable Documentation

◆ kDumpFormatVersion

constexpr uint16_t mm::node::kDumpFormatVersion = 1
inlineconstexpr

Current dump format version. A reader rejects an unknown major shape; bump on layout changes so old files stay identifiable.

◆ kDumpMagic

constexpr std::array<char, 4> mm::node::kDumpMagic = {'M', 'M', 'P', 'D'}
inlineconstexpr

Magic at the very start of every dump file.

◆ kDumpRowCountOffset

constexpr std::streamoff mm::node::kDumpRowCountOffset = 16
inlineconstexpr

Byte offset of the rowCount field within the fixed prefix. The writer streams rows first, then seeks here to patch the final count — so the stream must be seekable.

◆ kSynapticonVendorId

constexpr uint32_t mm::node::kSynapticonVendorId = 0x000022D2
inlineconstexpr

EtherCAT vendor ID of Synapticon (SOMANET drives).

Synapticon's EtherCAT Vendor ID (object 0x1018:01), the discriminator for a SOMANET drive. Defined here as the single source of truth for the SOMANET check.

For this vendor the CoE object dictionary is uniquely determined by (productCode, revisionNumber): Synapticon bumps the revision whenever the dictionary changes, so an on-disk cache keyed on identity alone can never serve definitions that do not match the device. That guarantee does not hold for arbitrary third-party vendors, which is why the cache is enabled by default only for this vendor (see ParameterCacheConfig::cacheAllVendors).