feat(basicmicro): MCP/RoboClaw packet-serial motor controller component

[finger563]

Description

New espp::Basicmicro component for Basicmicro MCP236/MCP266 (and the wider RoboClaw family) brushed-DC motor controllers, speaking their packet serial protocol over UART — phase 1 of MCP support (phase 2: CANopen/DS402 over espp::Twai is in a parallel PR).

• Host-buildable wire core (detail/basicmicro_core.hpp, zero ESP deps): CRC-16/XMODEM exactly per the manual's reference algorithm, big-endian codecs, packet build + reply validation (reply CRC seeded with sent address+command per §2.2.7; read requests carry no CRC, matching the wire spec).
• espp::Basicmicro (BaseComponent, std::error_code, std::function write/read transport, serialized transactions): duty/speed/accel drives (32–40), buffered speed(+accel)+distance moves (41–47), encoders (16–20/78/79/91), velocity PID get/set (28/29/55/56 — including the protocol's D,P,I order-on-write vs P,I,D-on-read quirk and 16.16 fixed-point scaling), firmware version / battery / currents / PWMs / temperatures / status, EEPROM write, E-stop reset. Every command number and payload layout verified against the MCP user manual; commands whose manual entries are ambiguous or contain documentation errors (e.g. 133/134's copy-paste error) were deliberately omitted rather than guessed — noted in the source.
• esp32 UART example (version → battery → status → gentle M1 duty ramp with encoder readback → stop → telemetry), standard espp example CMake conventions.
• Full registration: docs (rst + Doxyfile), build matrix, component upload, README with registry badge.

Testing

• Host golden tests: CRC vectors (incl. full real packets), codec round-trips, reply accept/reject (corrupt data/CRC, wrong seed, short reply) — ALL PASSED.
• esp32 example builds clean.
• cppcheck (CI settings): clean.
• Hardware validation on a real MCP is the remaining gate — the example + the upcoming MCP web console are the test vehicles.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Warning

Copilot couldn't run its full agentic review because it didn't start before the timeout. Make sure your repository has a runner available, or add a copilot-code-review.yml file specifying one with the runs-on attribute. See the docs for more details.

Adds a new espp::Basicmicro component implementing Basicmicro MCP/RoboClaw packet-serial protocol support, plus docs, example, CI integration, and host-side wire-core tests.

Changes:

• Introduces a host-buildable wire core (basicmicro_core.hpp) and the main espp::Basicmicro driver API (basicmicro.hpp).
• Adds an ESP-IDF UART example project and integrates it into build/docs/doxygen/component upload workflows.
• Adds host-side unit tests validating CRC, codecs, packet building, and reply validation.

Reviewed changes

Copilot reviewed 17 out of 17 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
doc/en/motor_control/index.rst	Adds Basicmicro docs page to the motor control doc index.
doc/en/motor_control/basicmicro_example.md	Includes the component example README into docs.
doc/en/motor_control/basicmicro.rst	Introduces Basicmicro component documentation + toctree to the example page.
doc/Doxyfile	Registers Basicmicro headers and example source for Doxygen generation.
components/basicmicro/test/basicmicro_host_test.cpp	Adds host-buildable golden tests for CRC/codecs/packet validation.
components/basicmicro/include/detail/basicmicro_core.hpp	Adds protocol wire-core helpers (CRC/codec/packet build/validate) and enums.
components/basicmicro/include/basicmicro.hpp	Adds the transport-agnostic Basicmicro driver API built on the wire core.
components/basicmicro/idf_component.yml	Adds component-manager manifest for publishing.
components/basicmicro/example/sdkconfig.defaults	Adds example sdkconfig defaults for task stack sizing.
components/basicmicro/example/main/basicmicro_example.cpp	Adds ESP-IDF UART example demonstrating common commands and telemetry.
components/basicmicro/example/main/CMakeLists.txt	Registers the example’s main component.
components/basicmicro/example/README.md	Documents wiring/build/flash steps for the example.
components/basicmicro/example/CMakeLists.txt	Adds standalone example project configuration.
components/basicmicro/README.md	Adds component-level README with features/protocol/testing notes.
components/basicmicro/CMakeLists.txt	Registers the component with IDF build system.
.github/workflows/upload_components.yml	Adds basicmicro to the component upload workflow list.
.github/workflows/build.yml	Adds the Basicmicro example to the CI build matrix.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[github-actions]

✅Static analysis result - no issues found! ✅

[Copilot]

Pull request overview

Copilot reviewed 17 out of 17 changed files in this pull request and generated 1 comment.

Suppressed comments (1)

components/basicmicro/include/basicmicro.hpp:803

• read_exact() breaks out of the loop on the first 0-byte read. If the transport returns 0 for a short per-call timeout while more bytes may arrive before the overall deadline, this will prematurely fail reads for multi-byte replies that arrive in fragments. Instead of breaking on n == 0, continue looping until deadline is reached (optionally with a small backoff/yield if needed), and only time out once the overall deadline elapses.

  bool read_exact(std::span<uint8_t> buf, std::error_code &ec) {
    const auto deadline = std::chrono::steady_clock::now() + config_.timeout;
    size_t got = 0;
    while (got < buf.size()) {
      const auto now = std::chrono::steady_clock::now();
      if (now >= deadline)
        break;
      const auto remaining = std::chrono::duration_cast<std::chrono::milliseconds>(deadline - now);
      const size_t n =
          config_.read(buf.subspan(got), std::max(remaining, std::chrono::milliseconds(1)));
      if (n == 0)
        break; // the read function timed out
      got += n;
    }
    if (got < buf.size()) {
      logger_.debug("timed out reading reply ({}/{} bytes)", got, buf.size());
      ec = std::make_error_code(std::errc::timed_out);
      return false;
    }
    ec.clear();
    return true;
  }

[Copilot]

Pull request overview

Copilot reviewed 17 out of 17 changed files in this pull request and generated 1 comment.

Suppressed comments (4)

components/basicmicro/example/main/basicmicro_example.cpp:88

• After any transient failure during the upward ramp, the next loop restarts at max_duty; if communication recovers, the motor jumps directly to 12.5% instead of ramping down from the last successfully commanded duty. Track that duty and use it as the downward loop's starting point.

  for (int16_t duty = 0; duty <= max_duty; duty = static_cast<int16_t>(duty + step)) {
    if (!mcp.drive_m1_duty(duty, ec)) {
      logger.error("drive_m1_duty({}) failed: {}", duty, ec.message());
      break;

components/basicmicro/example/main/basicmicro_example.cpp:109

• A failed final stop is silently ignored, after which the example enters its infinite telemetry loop while the motor may remain at its last commanded duty. Treat stop failure as a safety-critical error: log it and retry/abort normal execution rather than continuing as though the ramp completed.

  // make sure the motor is stopped
  if (mcp.drive_m1_duty(0, ec))
    logger.info("Motor stopped");

components/basicmicro/include/basicmicro.hpp:891

• Commands 18/19 return a 32-bit speed magnitude plus a separate direction byte; the official Basicmicro API likewise exposes this field as uint32_t. Decoding it as signed makes magnitudes with bit 31 set negative even though direction is already reported separately. Change this helper and both public output parameters to uint32_t (and update the example variable).

  bool read_speed(Command cmd, int32_t &qpps, uint8_t &direction, std::error_code &ec) {
    uint8_t data[5] = {};
    if (!read_command(cmd, data, ec))
      return false;
    qpps = detail::read_i32_be(data, 0);

components/basicmicro/example/main/basicmicro_example.cpp:49

• pdMS_TO_TICKS truncates. With a 100 Hz tick rate, a remaining timeout such as 19 ms becomes one 10 ms tick; if no byte arrives in that shorter interval, read_exact treats the callback's zero return as the final timeout even though its deadline has not elapsed. Round the duration up to the next tick so this transport honors the requested timeout.

This issue also appears in the following locations of the same file:

• line 85
• line 107

        const int read =
            uart_read_bytes(uart_port, data.data(), data.size(), pdMS_TO_TICKS(timeout.count()));
        return read < 0 ? 0 : static_cast<size_t>(read);

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.