feat(vesc): integrate native calibration diagnostics and configuration archives
This commit is contained in:
DCCONSTRUCTIONS
@@ -0,0 +1,253 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user