NODEDC_MISSION_CORE/plugins/vesc/README.md

VESC onboard plugin — profile 0.4.0

Native release in preparation: 0.4.0 / Node 0.8.30-1 uses the actual VESC Tool 7.00 C++ engine for USB ownership, commands, configuration codecs and Hall measurement. Installation and physical qualification are still pending.

Previous release status, 2026-09-23: 0.3.0 / Node 0.8.29-1 is an uninstalled, withheld experiment. The owner requires the actual upstream VESC Tool as the onboard engine behind Mission Core controls. Do not deploy the separate Python Hall workflow below as the intended calibration backend. Hardware currently runs 0.2.5 / Node 0.8.28-1. The verified native adapter and canonical procedure are documented in the native engine plan.

This increment discovers USB candidates, reads protocol identity and telemetry, saves opaque motor/application configuration backups and provides bounded identification pulses and user-assigned drive positions. It is not complete VESC Tool functional parity and does not implement continuous driving, configuration writes, calibration, CAN forwarding, custom configuration, firmware update or script execution.

Placement and ownership

One mission-core-vesc service owns the serial descriptors. The Node model registry admits only its Unix socket and explicit domain operations. Local Node UI and paired Core use the same SensorUiContribution and operation journal. VESC Tool is a text action in the existing device row, opening the existing Detail slot. No workspace, root, visual control or motor icon was added.

Candidates must match 0483:5740 and ChibiOS/RT Virtual COM Port. USB serial is never their durable identity: every candidate starts with a transport-local attachment including USB devnum. Only a valid firmware reply with a nonzero 12-byte UUID establishes a stable ID. Duplicate protocol UUIDs remain separate provisional rows and cannot receive read operations. Replug renews the session. Names and physical Left/Right roles must not be inferred from tty numbering.

The read-only serial path admits command bytes 0, 4, 14, 17, 31 and 62, with no arguments: identity, values, motor config, application config, decoded PPM and CAN discovery. The separate fixed test commands are described below. No keepalive, detect, config write, terminal or arbitrary packet API exists. Firmware identity is checked again before each operation; backup verifies it at the end as well. CRC/framing/length and response limits are enforced. Every port is held with flock/TIOCEXCL; an already running external tool must release it before this service is prepared.

Compatibility and backup

Wire reference is the official VESC Tool source, specifically packet.cpp, commands.cpp and datatypes.h. The reference identifies itself as test version 7.01; it is not installed by this profile. The first reader implements the common values prefix for motor firmware major 5–7 and hardware type 0 (or an older reply without hardware type). Exact board/firmware qualification remains a hardware acceptance result, not a claim from a version number alone. Unknown layouts may identify themselves but are not decoded.

Config replies are preserved as received, including command byte and signature, with SHA-256 and identity/version metadata. Their fields are not decoded without the exact firmware schema. The backups are not XML files importable into Tool, and this profile provides no restore action. Motor and application reads are sequential, not an atomic snapshot against other controller interfaces.

Read receipts and backups live privately in /var/lib/mission-core-vesc. Operation IDs bind the exact request; retries retrieve receipts. An interrupted request remains unknown rather than being silently replayed. This service's host storage is bounded and does not delete backups to make space. GUI telemetry is an explicitly requested timestamped snapshot, not a control loop or a waveform recorder. ERPM is not mechanical shaft RPM.

Packaging and first preparation

Node 0.8.22-1 carries this plugin from packaging/payload.py; no ad-hoc files, global Python packages or separate Qt installation are required. The source build pin is Design Guideline 8dd9190573d6616024ef01b9b34bf90b72960f44. The existing versioned owner installer installs Node. Its local Ubuntu sudo prompt belongs to the owner; no password is handled by Core or an agent.

The device's Prepare action starts only mission-core-node-vesc-prepare.service, via the existing Node polkit rule. The shipped profile creates the dedicated account, installs the exact-candidate udev rule, applies it to matching attached ttys and starts the read service. It does not add the operator or Node to dialout or disable ModemManager globally. Node retains PrivateDevices. The adapter has no capabilities, private network, read-only system files, bounded memory/tasks and a cdc_acm device cgroup rule. modprobe@cdc_acm ensures the named ttyACM group exists before cgroup resolution on cold boot; systemd DeviceAllow uses group names from /proc/devices, not char-<major-number>.

Before package replacement, the installer refuses an active preparation and stops the reader. A prepared profile restarts through its shipped job afterward. Removal stops/disables the service and removes only a byte-matching owned udev rule. Private backups and account identity are retained. Rolling Node back to 0.8.21-3 disables VESC support; do not claim an older package can restore the new UI or firmware configuration. No VESC firmware was changed by this profile.

Validation

Synthetic tests cover every denied transmit byte, fragmented/coalesced/corrupt frames, missing identities, scales, duplicate IDs, two independent attachments, replug sessions, receipts, config hashes and denied write actions. Node tests cover UUID promotion and preservation of camera guards. Full Node and Core checks are required alongside Linux package qualification and actual hardware reads. Test success is not clean-Ubuntu or motor calibration acceptance.

On the Mini, qmake, qmake6 and cmake were absent in the read-only build inventory. This first increment therefore uses the bounded reader fallback from the implementation plan. Headless extraction of the full upstream engine has not been demonstrated; it remains a separate build/compatibility task for the remaining Tool feature matrix.

0.2.1 — per-controller identification pulse and immutable archive

Node 0.8.24-1 adds a fixed 2 A pulse on one selected VESC, with a duration chosen from 1.5, 5 or 10 seconds. Discovery and session validation accept up to 128 directly attached controllers per board; there is no two-motor role enum. Names are the existing UUID-bound device names, scoped to their board. Synthetic 1/6/10-controller tests do not establish physical USB capacity. This is not a vehicle drive controller, completed RC arbiter, or calibration. All attached UUID sessions, firmware 5.02 / 75_300_R2, FOC, PPM Duty Cycle, neutral input for one second and a zero-current failsafe are mandatory. Official 5.02 schemas are included unchanged with their upstream license. Before any torque, motor and application configurations of every attached controller are archived durably, and each CAN segment is checked for unmanaged peers. Attachments are rechecked throughout the pulse. Each controller receives its own 250 ms volatile app-output lease (CAN-forward flag false). Other controllers receive zero current; the target receives only 2 A. A receiver command, serial fault, telemetry limit or local Stop ends the test. No config/firmware write, arbitrary current, arbitrary packet or CAN broadcast is exposed. Replaying an operation ID never repeats physical work.

Firmware PPM pulses reset the global timeout even during app-output pause; therefore the design relies on the expiring local app-output lease returning to the existing PPM neutral/missing-pulse behavior, not solely on USB timeout. RC activity latches further test requests until an explicit neutral release. This is a test-session guard, not continuous production RC takeover monitoring. Neutral PPM alone cannot prove transmitter/link availability. Host-independent lease behavior follows the pinned firmware source; real stop/failsafe qualification is still required and must not be claimed from synthetic tests.

Versions live in a private SQLite archive, are replicated via existing pairing with ACK after durable Core storage, and remain downloadable when a controller is offline. The Node and Core use the same detail component. The native VESC Tool 7.00 engineering build is separate: it has not acquired serial ownership or been integrated for calibration.

Package upgrades remove only generated bytecode below the installed VESC payload before preparation starts. Deterministic source mtimes can otherwise validate stale same-size .pyc files even with python -B; a regression test reproduces the failed 0.8.23-1 upgrade and verifies this installer-owned fix.

0.2.2 — entered test values and drive positions

Node 0.8.25-1 carries numeric current and duration fields. The board advertises and independently enforces 0.5–5 A and 0.5–10 seconds for this identification mode. These are software bounds, not controller or motor nameplate ratings. Existing 60 A motor / 55 A battery configuration is not evidence that the rig can safely sustain those currents. Above 2 A the test coasts at 400 electrical RPM and resumes current below 250, with a separate 800 ERPM abort threshold. Requested current is also bounded by the read configuration. Receipts distinguish successfully sent current commands from sampled cycles that ended before transmission. These bounds do not admit maximum-power tests.

The existing VESC detail offers one board-wide drive profile: 1×1 means left and right (two motors); 2×2 means left front, left rear, right front and right rear (four motors). Directions are relative to forward vehicle motion. Position is manually assigned after physical identification and persists by controller UUID, not USB address. The same component is used on Node and paired Core. Revision checks prevent stale updates; an occupied position cannot be stolen, and rear assignments must be explicitly removed before shrinking to 1×1. Changing profile/position is local metadata and sends no VESC command. Discovery itself remains independent of these two admitted layout presets.

0.2.3 — explain blocked tests and retain stop evidence

Numeric fields show validation errors beside invalid values. The action area explains why Start is unavailable, including confirmation reset after a test. A telemetry-bound stop retains the triggering sample and its field, measured value and unchanged bounds. A completed current pulse never proves physical rotation; the owner must observe the motor before assigning its position.

0.2.4 — gradual current in identification mode

The confirmed right motor crossed800ERPM within0.245s of a5A step. The next profile starts and resumes at0.5A, increasing by approximately1A/s toward the entered ceiling. Soft coasting triggers at200ERPM or4%PWM and only resumes below100ERPM and2%PWM. It applies to every allowed current, while the hard abort thresholds remain unchanged. This is an identification pulse governor, not a vehicle speed controller. Command receipts record actual requested current per sample, including ramp/coasting;5A input is a ceiling.

0.2.5 — entered current up to 30 A and time up to 30 seconds

At the owner's request the raised-rig test accepts 0.5–30 A and 0.5–30 s. These are software admission bounds, not motor/controller nameplate ratings. The selected controller's configured motor and input current limits still bind. Positive current starts at0.5A and ramps by2A/s; the entered value is a current ceiling, not a speed request. No configuration or firmware write is performed.

The former200ERPM/4%PWM coast/restart loop was causing the observed right-motor steps and pauses. This increment removes that automatic cycling. Current is maintained until time expires, Stop/RC/link interruption, or a telemetry limit. The test ends at6000ERPM or25%PWM (or a lower configured speed/duty limit), without automatic re-acceleration. A no-load motor can reach a speed limit before the entered time:30seconds is the maximum duration, not a promise of constant-speed rotation. Current feedback has bounded overshoot tolerance, capped by the configured motor current limit. Fault, voltage, temperature, identity/topology, neutral RC, expiring per-device leases and release checks remain active.

Above5A, a2-second interval without at least three net electrical tachometer steps at60ERPM ends the test. This uses the existing Hall/FOC estimate; it is not independent mechanical feedback or certified thermal protection, especially with a damaged sensor connection. It prevents continuing to raise commanded current while the reported rotor remains stationary. Sustained vehicle control, calibration and native VESC Tool parity remain separate unfinished work.

The owner clarified the diagnostic roles: LEFT is the problematic motor; RIGHT works normally from RC and is physically assigned right.1. Short steps in the earlier Core test must not be recorded as a right-motor defect. Every powered engineering experiment is coordinated with the owner at launch time.

0.3.0 — measured speed hold and native Hall measurement

vesc.motor.run calls firmware speed PID (COMM_SET_RPM), ramps the setpoint at 600 ERPM/s and counts time only after one second within 15% of the requested speed with a changing VESC tachometer. The UI exposes speed 300–3000 ERPM, motor-current ceiling 0.5–30 A and rotation time 0.5–30 s. Startup is bounded by 15 s; losing speed for 2 s ends the run. No automatic restart. FOC telemetry is not an independent physical encoder; the operator compares visible motion. The old vesc.motor.pulse action remains compatible but is not used by this UI.

Before a speed command, COMM_SET_MCCONF_TEMP applies current scaling to both positive and braking motor current. Store/CAN/divide flags are false. ACK and full configuration readback precede torque. A durable UUID-bound journal exists before the first write. Cleanup restores the exact original configuration, verified byte-for-byte. A lost ACK, disconnection or process interruption leaves the journal pending; discovery retries restoration only with a matching identity, zero current, neutral receiver and unchanged unrelated configuration. An external configuration change is never overwritten. No flash or application write is used. The operation transport permits 90 s, including preflight and acceleration.

vesc.hall.measure is the native FW 5.02 COMM_DETECT_HALL_FOC procedure also used by VESC Tool. It uses fixed 5 A, sweeps three electrical turns forward and three backwards, returns the observed table and restores its prior configuration. The table is not automatically applied. The firmware locks mc_interface during this approximately 12 s cycle; USB current-zero and receiver input cannot interrupt it. The UI requires a separate observed-rig/physical-power-cut acknowledgement and explicitly describes this limitation. Unknown completion latches authority and blocks another powered operation. Measurement, samples and backup references remain in the receipt.

These operations do not constitute the full VESC Tool desktop UI. The product entry is labelled “Настройка VESC” until complete native application session integration is shipped. Full R/L/flux calibration, table application and configuration restore remain separate unimplemented work.