Add encoder calibration check utility and documentation

doc/Doxyfile

@@ -17,19 +17,22 @@ OUTPUT_DIRECTORY       = _build
 STRIP_FROM_PATH        = ..
 STRIP_FROM_INC_PATH    = ../src/CiA402/include \
                          ../device/CiA402MotionControl \
-                         ../utils/StoreHomePosition/include
+                         ../utils/StoreHomePosition/include \
+                         ../utils/CheckEncoderCalibration/include
 
 # -- Input --
-INPUT                  = ../README.md \
-                         ../device/CiA402MotionControl \
+INPUT                  = ../device/CiA402MotionControl \
                          ../src/CiA402/include \
                          ../src/CiA402/src \
                          ../utils/StoreHomePosition/include \
                          ../utils/StoreHomePosition/src \
+                         ../utils/CheckEncoderCalibration/include \
+                         ../utils/CheckEncoderCalibration/src \
                          ./main.md \
                          ./dual_encoder_handling.md \
                          ./modes_and_setpoints.md \
-                         ./protocol_map.md
+                         ./protocol_map.md \
+                         ./check_encoder_calibration.md
 
 FILE_PATTERNS          = *.h *.cpp *.md
 RECURSIVE              = YES

doc/check_encoder_calibration.md

@@ -0,0 +1,129 @@
+# Check Encoder Calibration {#check_encoder_calibration}
+
+[TOC]
+
+## Purpose
+
+After a homing / calibration run (performed by @ref CiA402::StoreHome37), the
+encoder positions are persisted on each drive's non-volatile memory and a TOML
+snapshot is written to disk. Over time — due to mechanical play, power cycles,
+firmware updates, or unexpected faults — the actual encoder readings may drift
+from the reference values recorded in that TOML file.
+
+**`check-encoder-calibration`** is a read-only diagnostic tool that:
+
+1. Reads the reference TOML file produced by `store-home-position`.
+2. Connects to all EtherCAT slaves via SDO (no cyclic motion is commanded).
+3. Reads back each encoder channel's current raw and adjusted positions plus
+   resolution parameters.
+4. Computes the delta between the recorded and live values.
+5. Writes a **Markdown report** with summary and per-slave comparison tables.
+
+> The ring stays in SAFE-OP / PRE-OP throughout; no drive parameters are
+> modified.
+
+## SDOs Read
+
+| SDO      | Sub    | Type  | Description                        |
+|:--------:|:------:|:-----:|------------------------------------|
+| `0x2110` | `:03`  | UDINT | Encoder 1 resolution (counts/rev)  |
+| `0x2111` | `:01`  | UDINT | Encoder 1 raw position             |
+| `0x2111` | `:02`  | DINT  | Encoder 1 adjusted position        |
+| `0x2112` | `:03`  | UDINT | Encoder 2 resolution (counts/rev)  |
+| `0x2113` | `:01`  | UDINT | Encoder 2 raw position             |
+| `0x2113` | `:02`  | DINT  | Encoder 2 adjusted position        |
+
+These are the same objects written to the TOML snapshot by
+@ref CiA402::StoreHome37 — see @ref protocol_map for the full object
+dictionary.
+
+## Command-Line Usage
+
+```bash
+yarp-cia402-check-encoder-calibration \
+    --ifname eth0 \
+    --toml-input joint_calibration_2026_03_04_18_54_35.toml \
+    --report-output calibration_check.md
+```
+
+### Parameters
+
+| Key              | Type   | Description                                                  | Default |
+|:----------------:|:------:|--------------------------------------------------------------|:-------:|
+| `ifname`         | string | Network interface used by SOEM                               | `eth0`  |
+| `toml-input`     | string | **(required)** Reference TOML file from `store-home-position`| —       |
+| `report-output`  | string | Path of the Markdown report to write                         | `encoder_calibration_check_YYYY_MM_DD_HH_MM_SS.md` |
+
+Parameters can also be provided via a YARP `.ini` file:
+
+```ini
+# check_calibration.ini
+ifname eth0
+toml-input joint_calibration_2026_03_04_18_54_35.toml
+report-output calibration_check.md
+```
+
+```bash
+yarp-cia402-check-encoder-calibration --from check_calibration.ini
+```
+
+## Report Format
+
+The generated Markdown file has three sections:
+
+### Header
+
+| | |
+|:--|:--|
+| **Date** | 2026-03-05 14:30:00 |
+| **Reference TOML** | `joint_calibration_2026_03_04_18_54_35.toml` |
+| **Slaves checked** | 3 |
+
+### Summary Table
+
+One row per slave with the adjusted-position delta in degrees for quick
+pass / fail inspection:
+
+| Slave | Name    | Enc1 Adj Δ (deg)  | Enc2 Adj Δ (deg)  |
+|:-----:|:--------|------------------:|------------------:|
+| 1     | SOMANET | +0.001234         | −0.000567         |
+| 2     | SOMANET | +0.000000         | +0.000012         |
+
+### Per-Slave Detailed Tables
+
+Two tables per slave (Encoder 1, Encoder 2) with full comparison:
+
+| Metric                     | Reference (TOML) | Current (Live) | Delta     |
+|:---------------------------|-----------------:|---------------:|----------:|
+| Raw position (counts)      | 2461952          | 2461960        | +8        |
+| Raw position (deg)         | 350.753906       | 350.754047     | +0.000141 |
+| Adjusted position (counts) | 2461952          | 2461960        | +8        |
+| Adjusted position (deg)    | 350.753906       | 350.754047     | +0.000141 |
+| Counts per revolution      | 2527232          | 2527232        | 0         |
+| Raw-to-degrees factor      | 0.000142         | 0.000142       | +0.000000 |
+
+## Typical Workflow
+
+```text
+  store-home-position              check-encoder-calibration
+  ───────────────────              ─────────────────────────
+  Calibrate all drives   ──►  reference.toml
+                                          │
+                                          ▼
+                                  Read reference + live SDOs
+                                          │
+                                          ▼
+                                  Write Markdown report
+```
+
+```bash
+# 1. Calibrate (done once or when needed)
+yarp-cia402-store-home-position --ifname eth0 --toml-output reference.toml
+
+# 2. Later, verify calibration integrity
+yarp-cia402-check-encoder-calibration --ifname eth0 --toml-input reference.toml
+```
+
+## API Reference
+
+- @ref CiA402::CheckEncoderCalibration — main application class.

doc/main.md

@@ -25,6 +25,9 @@ profile over EtherCAT (CoE).
   converted to drive units.
 - **Home-position utility** — standalone tool to set and persist homing
   parameters on the drive's non-volatile memory.
+- **Calibration check utility** — read-only diagnostic that compares live
+  encoder readings against a reference TOML snapshot and produces a Markdown
+  report.
 
 ## Documentation sections
 
@@ -36,6 +39,8 @@ profile over EtherCAT (CoE).
 | @ref yarp::dev::CiA402MotionControl | Main device driver API reference. |
 | @ref CiA402::EthercatManager | Low-level EtherCAT master (SOEM wrapper). |
 | @ref CiA402::StoreHome37 | Home-position persistence utility. |
+| @subpage check_encoder_calibration | Encoder calibration check utility — compare live readings vs. reference TOML. |
+| @ref CiA402::CheckEncoderCalibration | Calibration-check utility API reference. |
 
 ## Getting started
 

utils/CMakeLists.txt

@@ -1 +1,2 @@
 add_subdirectory(StoreHomePosition)
+add_subdirectory(CheckEncoderCalibration)

utils/CheckEncoderCalibration/CMakeLists.txt

@@ -0,0 +1,5 @@
+add_application(
+    NAME check-encoder-calibration
+    SOURCES src/main.cpp src/CheckEncoderCalibration.cpp
+    HEADERS include/CheckEncoderCalibration/CheckEncoderCalibration.h
+    LINK_LIBRARIES YarpCiA402::EthercatManager YARP::YARP_os YARP::YARP_dev tomlplusplus::tomlplusplus)

utils/CheckEncoderCalibration/README.md

@@ -0,0 +1,114 @@
+# Check Encoder Calibration 🔍
+
+## Overview 🌟
+Utility to verify encoder calibration integrity on EtherCAT CiA402 drives. It:
+- Connects to all slaves on the specified network interface via SDO.
+- Reads the current encoder positions (raw and adjusted) and resolutions for both encoder channels.
+- Compares the live values against a reference TOML file previously written by `store-home-position` after calibration.
+- Generates a human-readable **Markdown report** with a summary table and per-slave detailed comparison tables showing reference values, current values, and deltas.
+
+This allows an operator to quickly spot whether encoder state has drifted since the last calibration without re-running the homing procedure.
+
+> Note: Tested on Linux. Requires raw-socket/network admin capabilities to access EtherCAT via SOEM.
+
+## Post-Install Setup 🔧
+After installing the project, make sure the binary can find its libraries and has the required capabilities:
+
+```console
+patchelf --add-rpath $(dirname $(dirname $(which yarp-cia402-check-encoder-calibration)))/lib $(which yarp-cia402-check-encoder-calibration)
+sudo setcap 'cap_net_raw,cap_net_admin+ep' "$(readlink -f $(which yarp-cia402-check-encoder-calibration))"
+```
+
+## Usage 🚀
+
+Run the tool with the reference TOML file from a previous calibration:
+
+```bash
+yarp-cia402-check-encoder-calibration \
+	--ifname eth0 \
+	--toml-input joint_calibration_2026_03_04_18_54_35.toml \
+	--report-output calibration_check.md
+```
+
+### Options ⚙️
+- `--ifname`: Network interface used by SOEM (default: `eth0`).
+- `--toml-input`: **(required)** Path of the reference TOML file produced by `store-home-position`.
+- `--report-output`: Path of the Markdown report to write (default: `encoder_calibration_check_<YYYY>_<MM>_<DD>_<HH>_<MM>_<SS>.md`).
+
+### Configuration file (optional) 📝
+You can also provide options through a YARP `.ini` file and pass it with `--from`:
+
+```ini
+# check_calibration.ini
+ifname eth0
+toml-input joint_calibration_2026_03_04_18_54_35.toml
+report-output calibration_check.md
+```
+
+Run with:
+
+```bash
+yarp-cia402-check-encoder-calibration --from check_calibration.ini
+```
+
+## What It Does 🧠
+1. Parses the reference TOML file produced by `store-home-position`.
+2. Initializes the EtherCAT master on `--ifname` and discovers all slaves.
+3. For each slave found in both the bus and the TOML file, reads the following SDOs:
+
+| SDO        | Sub  | Type  | Description                                      |
+|:----------:|:----:|:-----:|--------------------------------------------------|
+| `0x2110`   | `:03`| UDINT | Encoder 1 resolution (counts/rev)                |
+| `0x2111`   | `:01`| UDINT | Encoder 1 raw position                           |
+| `0x2111`   | `:02`| DINT  | Encoder 1 adjusted position                      |
+| `0x2112`   | `:03`| UDINT | Encoder 2 resolution (counts/rev)                |
+| `0x2113`   | `:01`| UDINT | Encoder 2 raw position                           |
+| `0x2113`   | `:02`| DINT  | Encoder 2 adjusted position                      |
+
+4. Compares each value against the reference and computes the delta.
+5. Writes a Markdown report.
+
+## Report Structure 📄
+
+The generated Markdown report contains:
+
+### 1. Header
+General information: date/time, reference TOML path, number of slaves checked.
+
+### 2. Summary Table
+A quick-glance table with one row per slave showing the adjusted-position delta in degrees for both encoder channels:
+
+| Slave | Name    | Enc1 Adj Δ (deg) | Enc2 Adj Δ (deg) |
+|:-----:|:--------|------------------:|------------------:|
+| 1     | SOMANET | +0.001234         | -0.000567         |
+| 2     | SOMANET | +0.000000         | +0.000012         |
+
+### 3. Per-Slave Detailed Tables
+For each slave, two tables (Encoder 1 and Encoder 2) with full comparison:
+
+| Metric                    | Reference (TOML) | Current (Live) | Delta     |
+|:--------------------------|----------------:|---------------:|----------:|
+| Raw position (counts)     | 2461952          | 2461960        | +8        |
+| Raw position (deg)        | 350.753906       | 350.754047     | +0.000141 |
+| Adjusted position (counts)| 2461952          | 2461960        | +8        |
+| Adjusted position (deg)   | 350.753906       | 350.754047     | +0.000141 |
+| Counts per revolution     | 2527232          | 2527232        | 0         |
+| Raw-to-degrees factor     | 0.000142         | 0.000142       | +0.000000 |
+
+## Example Workflow 🔄
+
+```bash
+# 1. Calibrate and save reference (done once)
+yarp-cia402-store-home-position --ifname eth0 --toml-output calibration_ref.toml
+
+# 2. Later, verify calibration is still valid
+yarp-cia402-check-encoder-calibration --ifname eth0 --toml-input calibration_ref.toml
+
+# 3. Open the generated report
+cat encoder_calibration_check_2026_03_05_14_30_00.md
+```
+
+## Safety Notes ⚠️
+- This tool performs **read-only** SDO communication; it does not modify any drive parameters.
+- The EtherCAT ring stays in SAFE-OP/PRE-OP throughout; no cyclic motion is commanded.
+- If a slave present on the bus has no matching entry in the TOML reference file, it is skipped with a warning.

utils/CheckEncoderCalibration/include/CheckEncoderCalibration/CheckEncoderCalibration.h

@@ -0,0 +1,87 @@
+// SPDX-FileCopyrightText: Generative Bionics
+// SPDX-License-Identifier: BSD-3-Clause
+
+#ifndef CHECK_ENCODER_CALIBRATION_H
+#define CHECK_ENCODER_CALIBRATION_H
+
+#include <cstdint>
+#include <memory>
+#include <string>
+
+#include <yarp/os/ResourceFinder.h>
+
+namespace CiA402
+{
+
+/**
+ * @brief Encoder calibration checker: compare live encoder readings against a reference TOML file.
+ *
+ * This utility connects to all EtherCAT slaves on the specified network interface using SDO
+ * communication and reads back the current encoder positions (raw and adjusted) and resolutions
+ * for both encoder channels. It then compares these live values against a reference TOML file
+ * previously written by @ref CiA402::StoreHome37 (store-home-position application) immediately after calibration.
+ *
+ * The result is a human-readable Markdown report containing one table per slave, showing:
+ *  - The reference value from the TOML file.
+ *  - The current live value read from the drive.
+ *  - The difference (delta) between the two.
+ *
+ * This allows an operator to quickly verify whether the encoder state has drifted since the last
+ * calibration, without re-running the full homing procedure.
+ *
+ * @note Only SDO communication is used; the ring stays in SAFE-OP/PRE-OP throughout.
+ * @note SOEM uses 1-based slave indices; the TOML file must follow the same convention
+ *       (@c slave_1, @c slave_2, …).
+ */
+class CheckEncoderCalibration
+{
+public:
+    /**
+     * @brief Default constructor.
+     *
+     * Allocates the internal implementation object. No EtherCAT communication is started.
+     */
+    CheckEncoderCalibration();
+
+    /**
+     * @brief Destructor.
+     *
+     * Releases all resources owned by the implementation. If the EtherCAT master was
+     * initialised, it is cleanly shut down.
+     */
+    ~CheckEncoderCalibration();
+
+    /// @cond — non-copyable
+    CheckEncoderCalibration(const CheckEncoderCalibration&) = delete;
+    CheckEncoderCalibration& operator=(const CheckEncoderCalibration&) = delete;
+    /// @endcond
+
+    /**
+     * @brief Run the full encoder check and produce a Markdown report.
+     *
+     * Reads configuration from the provided ResourceFinder, discovers all EtherCAT slaves on
+     * the specified network interface, reads each slave's encoder data, compares it against
+     * the reference TOML file, and writes a Markdown report to disk.
+     *
+     * @param rf ResourceFinder populated with the parameters listed below.
+     * @return @c true if the check completed successfully and the report was written;
+     *         @c false on any error (initialisation failure, TOML parse error, SDO read failure,
+     *         file I/O error).
+     *
+     * @note Expected keys in the ResourceFinder:
+     * | Key              | Type        | Description                                           | Default                    |
+     * |:----------------:|:-----------:|-------------------------------------------------------|:--------------------------:|
+     * | ifname           | string      | Network interface name (e.g. @c "eth0")               | @c "eth0"                  |
+     * | toml-input       | string      | Path of the reference TOML file (from StoreHome37)    | *(required)*               |
+     * | report-output    | string      | Path of the Markdown report to write                  | @c "encoder_calibration_check_YYYY_MM_DD_HH_MM_SS.md" |
+     */
+    bool run(yarp::os::ResourceFinder& rf);
+
+private:
+    class Impl;
+    std::unique_ptr<Impl> m_impl; ///< Opaque implementation (PIMPL idiom).
+};
+
+} // namespace CiA402
+
+#endif // CHECK_ENCODER_CALIBRATION_H