Confirm V5.5 (YST-DXT-J20) compatibility, modern flashing docs, ADC auto-calibration - #3
Open
Teuflor wants to merge 7 commits into
Open
Confirm V5.5 (YST-DXT-J20) compatibility, modern flashing docs, ADC auto-calibration#3Teuflor wants to merge 7 commits into
Teuflor wants to merge 7 commits into
Conversation
added 7 commits
July 23, 2026 09:22
…+ fix - Add docs/V5.5-mainboard-notes.md: SWD chip-ID confirmation that V5.5 boards use the same AT32F413RCT7 controller, factory-enabled Flash Access Protection (FAP) behavior, wiring gotchas (V3.3 sense line, no physical power button), and the GCC 14 -fcommon note. - Add docs/FLASHING_GUIDE.md: from-scratch flashing walkthrough using a modern OpenOCD (0.12.0+) with the native Artery driver, plus a troubleshooting table. - Add tools/at32f413_fap_disable.cfg: OpenOCD script working around a driver bug where `artery fap disable` uses a 5ms timeout for the USD erase step instead of the correct ~500ms, causing it to reliably fail on this chip. - README: link the new docs, note GCC 10+ needs -fcommon (already applied in the Makefile).
Ported the idea (not the code, different HAL/flash driver on this chip) from EFeru's hoverboard-firmware-hack-FOC VARIANT_ADC auto-calibration, scoped down to a single feature rather than its full input-abstraction system: hold the power-button jumper for 3s at boot to enter calibration, move both potentiometers through their range within 15s, and the learned min/center/max values are written to the last flash page and used from then on (falling back to the config.h ADC1/2_MIN/CENTER/MAX defaults until the first successful calibration). Opt-in via ADC_AUTO_CALIBRATION in config.h (enabled here, since this is this board's actual control mode). No change in behavior when disabled.
…lash Wiring GND/SWDIO/SWCLK only, exactly as the README instructed, made OpenOCD fail at the very first connection attempt (STLINK_JTAG_GET_IDCODE_ERROR) — it never got far enough to even read the chip ID, let alone flash. V3.3 still needs to be connected so the ST-Link has a logic-level reference for SWDIO/SWCLK; the existing "don't power from the programmer's 3.3V" warning is about current sourcing, not about leaving this pin disconnected entirely.
- Fix clone URL (was pointing at an unrelated "someone42" repo, leftover from further upstream) - Move the old stm32f2x-driver-patch flashing instructions into a collapsed "only if your OpenOCD lacks Artery support" section, with docs/FLASHING_GUIDE.md as the primary path - Add a short Documentation section linking the two docs/ files up top - Mention ADC_AUTO_CALIBRATION in the ADC troubleshooting note - Misc: dedupe repeated warnings, minor copyedits, consistent V5.1/V5.5 wording
- README.de.md: full German translation, cross-linked with README.md - Confirmed across several sessions that the power-button jumper only matters for the very first unlock of a still-protected chip — every flash after that works with just battery + ST-Link, no need to touch the jumper. Documented in README (both languages), FLASHING_GUIDE.md, and V5.5-mainboard-notes.md.
Board silkscreen confirms "YST-DXT-J20 V5.5" - a board family used across multiple hoverboard brands (not Bluewheel-specific), seen across several hoverboard-firmware-hack forks' issue trackers with different chips depending on batch (AT32F403RCT6, AT32F413RCT7, GD32F103RCT6). Found an independent report of the same factory-enabled FAP issue on a YST-DXT-J20 V5.7 board, corroborating this isn't a one-off. Also noted visible connectors from a reference photo (SW likely = power button, BAT-, motor phase color labels) and left the mystery ~1.2V 2-pin connector as an open question pending physical identification.
…Init Replace the old unframed 4-byte struct DMA-overlay (any dropped/extra byte permanently desyncs the stream forever) with the same framing EFeru's hoverboard-firmware-hack-FOC and its "hoverSerial.ino" reference sketch use: 2-byte start marker + steer + speed + XOR checksum, validated against a circular DMA buffer (byte-count-since-last-check must exactly match one packet, mirroring their usart2_rx_check() design) rather than a dedicated IDLE-line interrupt, so it's called once per main loop iteration instead - same correctness, no new interrupt wiring needed. A malformed/corrupted packet is silently dropped and the previous steer/speed values are kept. While test-building this under CONTROL_SERIAL_USART2 (never done before on this AT32 fork), found that UART_Control_Init() in setup.c is unrelated pre-existing dead code: it uses STM32-HAL-style calls (HAL_UART_Init, GPIO_InitTypeDef, ...) that don't exist in this fork's SPL-style AT32 driver, so it has never actually compiled since this port was created. Flagged clearly in config.h - the new protocol code is ready and compiles fine standalone, but is unreachable until that init function is rewritten (RX pin + RX DMA channel, following the working DEBUG_SERIAL_USART2 pattern in the same file) and verified on real hardware. Left unfixed for now: no UART source or motors at hand to test against, and getting low-level peripheral/DMA config wrong silently is a real risk not worth taking blind. Does not affect the currently active CONTROL_ADC_JOYSTICK config - builds clean, only +4 bytes (the Serialcommand struct grew by two uint16_t fields regardless of which input mode is active).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Brought up a board labeled V5.5 (silkscreen:
YST-DXT-J20 V5.5, from aBluewheel offroad hoverboard) and documented everything found along the way,
plus one small opt-in feature.
assuming from the label) — it's the same AT32F413RCT7 this repo targets.
See
docs/V5.5-mainboard-notes.md.docs/FLASHING_GUIDE.md: a from-scratch flashing walkthrough using acurrent OpenOCD (0.12.0+) with its native Artery driver — no more need for
the old patched-
stm32f2xworkaround.tools/at32f413_fap_disable.cfg: a workaround for a driver bug wherethe official
artery fap disableOpenOCD command times out on this chip(waits 5ms instead of ~500ms+ for the USD erase to finish). Root-caused
against openocd's actual
artery.csource.Inc/config.h/Src/main.c: opt-inADC_AUTO_CALIBRATIONforCONTROL_ADC_JOYSTICK— hold the power-button jumper 3s at boot to learnADC min/center/max by moving the potis, persisted to the last flash page.
No behavior change when the flag is off (default).
a collapsed fallback section, added a German translation
(
README.de.md), and documented that the power-button jumper is onlyneeded for the very first unlock of a still-protected chip (confirmed
across several sessions — not needed for any flash after that).
-fcommonfix for thertPmultiple-definition linker error(tentative vs. real definition,
-fno-commonbecame GCC's default inGCC 10).
Also found and cross-referenced an independent report
(#230)
of the same factory-enabled Flash Access Protection on another
YST-DXT-J20 board, for anyone who finds this board family confusing.
Test plan
without
ADC_AUTO_CALIBRATIONprogram ... verify reset exit) onreal hardware, multiple times across sessions
ADC_AUTO_CALIBRATIONbuilds and flashes; full end-to-end test (motorsattached, calibration gesture, verifying motor response) still pending
on my end — no motors currently connected to this board