254 lines
16 KiB
Markdown
254 lines
16 KiB
Markdown
# 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](../../docs/node/18_VESC_TOOL_NATIVE_BACKEND.md).
|
||
|
||
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](https://github.com/vedderb/vesc_tool/tree/dc53c658cbb89a947246034f7a00149cf79abdfc),
|
||
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](https://www.freedesktop.org/software/systemd/man/latest/systemd.resource-control.html#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.
|