espp/mcp266

1.4.4

Latest
uploaded 5 hours ago
Dual-channel Basicmicro MCP266 (RoboClaw family) motor controller over CANopen (CiA 402 profile position)

Readme

# MCP266 CANopen Motor Controller Component

[![Badge](https://components.espressif.com/components/espp/mcp266/badge.svg)](https://components.espressif.com/components/espp/mcp266)

The `Mcp266` class is a dual-channel controller for a Basicmicro **MCP266**
(RoboClaw family) brushed-DC motor driver over **CANopen**. It is layered on
`espp::CanopenClient` (like `espp::Ds402Drive`), so it is transport-agnostic:
the application owns the CAN transport, feeds received frames to the client's
`process_frame()`, and the client's node id selects the MCP266.

Both motor channels (`M1`, `M2`) are driven symmetrically. M2's CiA 402
objects mirror M1's at `+0x800`, handled through `Ds402Drive`'s object offset.

## What works, and what does not

**Position control** uses the standard CiA 402 profile position mode
(`move_to_position`) and is the supported, validated capability. It needs the
position loop configured first (`configure_position_loop`).

**Velocity / duty control is not functional** on the MCP266 firmware tested.
The standard target objects and the manufacturer speed/duty command mirror are
both accepted by the drive but leave the velocity generator idle even with the
drive in Operation Enabled. Supported-drive-modes (`0x6502`) advertises only
the cyclic-sync modes, so velocity likely requires csv mode with cyclic
SYNC/PDO updates, which is undocumented for this device. `drive_speed` /
`drive_duty` are implemented but are currently a no-op for motion; use position
mode.

## Device specifics

The MCP266's control-loop parameters are **not** standard CiA 402 objects. The
MCP mirrors its packet-serial command set into the manufacturer region of the
object dictionary at index `0x2000 + command number` (see
`include/detail/mcp266_core.hpp`, which is host-buildable and unit-tested).
This component uses that to:

* configure the position PID (commands 61-64), read the record back
  (`read_position_pid`, `read_position_limits`) and install tuned gains
  (`set_position_pid`),
* set an axis's encoder count (22/23, `set_encoder`) or zero both (20,
  `reset_encoders`) — how a quadrature encoder is homed against a limit switch
  or restored to a remembered position after power-up,
* set and read back the stored default speed and accel (68-72, 81:
  `set_default_speed`, `set_default_accel`, `read_default_speeds`,
  `read_default_accels`) — see below,
* issue the manufacturer speed/duty commands (32/33, 35/36), and
* read telemetry: main battery (24) and temperature (82).

Two device quirks are handled by `configure_position_loop()`, which must be
called once per boot (the MCP reverts to its EEPROM configuration on power-up):

* The position PID's `MinPos`/`MaxPos` clamp defaults to `[0, 0]`, which forces
  every position target to zero — it is widened here.
* The setter (commands 61/62) uses field order `D, P, I` while the readback
  (63/64) uses `P, I, D`, so a naive read-modify-write of the record would move
  `P` into the `D` slot and zero `P`. The correct field shuffle (and seeding a
  non-zero `P` when the record has none) is done here.

The position PID readback (63/64) is always read from subindex 1, including by
`read_position_limits`: on the MCP266 firmware tested (1.4.9) its `MinPos` /
`MaxPos` subindices (6, 7) read 0 when read on their own, and the stored values
when read after subindices 1..5.

**The motion profile is a stored setting, not a per-move one.** Profile-position
moves run on the controller's stored *default speed* and *default accel*: the
move's profile velocity (`0x6081`) is honoured below the stored speed, which
acts as a ceiling, and the stored accel is the ramp, while the CiA 402 profile
acceleration / deceleration objects are accepted but not applied (verified on
an MCP266 with a 50 counts/s² stored accel). `set_default_speed()` and
`set_default_accel()` write those stored values through the mirror (70/71 and
68/69). They take effect at once, but the controller reloads its EEPROM on
power-up and the write-settings command (94) did not persist them on the unit
tested, so install them at every boot alongside `configure_position_loop()`.
Note that Motion Studio's position page shows the parameters of its own slider
moves, which are not these stored values. The command's decel field is accepted
but inert on the firmware tested, which keeps one ramp per axis.

## Example

The [example](./example) brings up an `espp::Twai` transport (with
`tx_retry_count = -1`; see the canopen README) and an `espp::CanopenClient`,
NMT-starts the node, reads telemetry, configures the M1 position loop, and runs
a small profile-position sequence.

## Web console: `Mcp266Service` + `mcp266_protocol.hpp`

The [MCP266 Console](https://esp-cpp.github.io/espp/apps/mcp266_console.html)
(`web/mcp266_console.html`) drives an MCP266 from the browser over USB (WebUSB
or Web Serial) with a small high-level protocol — the CANopen/DS402 work stays
on the device. Opened with
`?autoconnect=1&transport=usb|serial&vid=0x1209&pid=...[&serial=...]` (the
query the Device Hub's links carry) it connects on load, without the browser
chooser, to a device the page was already granted; its **auto-reconnect**
checkbox (default on, remembered per origin) reconnects after an unexpected
link loss such as a device reboot or re-plug. Both only see devices the browser
already granted to the page (served over HTTPS, or HTTP on localhost; a
`file://` copy loses the
grant on reload).

- `mcp266_protocol.hpp` — the wire protocol (dispatcher **module 6** by
  default — `Mcp266Service::Config::module` moves an instance, and the console
  finds it through discovery by its protocol id `espp.mcp266`; `stream_frame`
  framing): request/reply
  types, the payload structs
  (`ConfigurePositionLoop`, `MoveToPosition`, `Status`, `DeviceInfo`, ...) with
  `serialize()` / `parse()`. Standard-library only, so it is usable from any
  client (host tests in `test/mcp266_protocol_host_test.cpp`).
- `mcp266_service.hpp` — `espp::Mcp266Service`: the device side as a
  [dispatcher](../dispatcher) service around an `espp::Mcp266`. It executes each
  request under a shared MCP mutex (one SDO channel), replies after releasing
  it, and runs the periodic STATUS stream (period clamped to a bus-safe range).
  Register it in one call, one instance per byte stream:

```cpp
espp::Mcp266 mcp(client, {...});
std::mutex mcp_mutex; // shared by every user of `mcp`
espp::Mcp266Service service(mcp, {.send = send, .mcp_mutex = &mcp_mutex});
espp::DispatcherWorker link({.send = send});
link.register_module(service);
link.serve_discovery("espp MCP266 Console");
usb.set_vendor_receive_callback([&](std::span<const uint8_t> data) { link.push(data); });
```

The [webapp example](./webapp_example) does exactly this on both the vendor
(WebUSB) and CDC (Web Serial) interfaces of an ESP32-S3.

## Related components

* `espp/canopen` — the CANopen client and the `Ds402Drive` CiA 402 helper this
  component builds on.
* `espp/basicmicro` — the Basicmicro **packet serial** protocol driver (a
  different transport to the same controller family), including velocity and
  position PID configuration over UART.

Links

Supports all targets

Maintainer

  • William Emfinger <waemfinger@gmail.com>
To add this component to your project, run:

idf.py add-dependency "espp/mcp266^1.4.4"

download archive

Stats

  • Archive size
    Archive size ~ 64.42 KB
  • Downloaded in total
    Downloaded in total 69 times
  • Weekly Downloads Weekly Downloads (All Versions)
  • Downloaded this version
    This version: 0 times

Badge

espp/mcp266 version: 1.4.4
|