Skip to content

Commit f8a5ef2

Browse files
FelipeMdeOFelipeMdeO
committed
ht32f491x3/esk32: add docs and flash helpers
Document the HT32F491x3 ESK32 board, build steps, flashing flow, and validation commands. Add WSL and PowerShell flash backends plus a Python wrapper. Signed-off-by: Felipe Moura <moura.fmo@gmail.com>
1 parent 166197e commit f8a5ef2

7 files changed

Lines changed: 554 additions & 5 deletions

File tree

‎Documentation/platforms/arm/ht32f491x3/boards/esk32/ht32f491x3-starter-kit.jpg‎

206 KB
Loading

‎Documentation/platforms/arm/ht32f491x3/boards/esk32/index.rst‎

Lines changed: 177 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,177 @@
1+
==================
2+
ESK32 (HT32F49163)
3+
==================
4+
5+
.. tags:: arch:arm, chip:ht32f491x3, chip:ht32f49163, vendor:holtek
6+
7+
The ESK32 is a development board based on the Holtek HT32F49163 MCU.
8+
The current NuttX port targets the HT32F49163 device used on the
9+
HT32F49163 development kit and focuses on a working serial-console NSH
10+
configuration with basic board bring-up.
11+
12+
For additional hardware details, refer to Holtek's
13+
`HT32F491x3 Starter Kit User Guide <https://www.holtek.com/webapi/106680/HT32F491x3_StarterKitUserManualv100.pdf>`_.
14+
15+
.. figure:: ht32f491x3-starter-kit.jpg
16+
:align: center
17+
:alt: HT32F491x3 Starter Kit
18+
19+
HT32F491x3 Starter Kit board photo
20+
21+
Features
22+
========
23+
24+
The current port provides:
25+
26+
* Holtek HT32F49163 MCU from the HT32F491x3 family
27+
* ARM Cortex-M4 core with FPU support
28+
* Boot and clock initialization for the ESK32 8 MHz external crystal
29+
* System clock configured to 150 MHz
30+
* USART1 serial console at 115200 8N1
31+
* ``/bin`` mounted through ``binfs``
32+
* ``/proc`` mounted through ``procfs``
33+
* User LED registration through ``/dev/userleds``
34+
* Basic internal GPIO helpers used by the console and LED support
35+
36+
The default ``esk32:nsh`` configuration also enables these built-in
37+
applications:
38+
39+
* ``hello``
40+
* ``ostest``
41+
* ``dumpstack``
42+
* ``leds``
43+
44+
Buttons and LEDs
45+
================
46+
47+
Board LEDs
48+
----------
49+
50+
Three user LEDs from the development kit are currently mapped by the board
51+
port. They are active-low and are exposed through the standard NuttX
52+
``USERLED`` interface and the ``/dev/userleds`` device.
53+
54+
===== =========== ==========
55+
LED Port/Pin Notes
56+
===== =========== ==========
57+
LED2 PD13 Active-low
58+
LED3 PD14 Active-low
59+
LED4 PD15 Active-low
60+
===== =========== ==========
61+
62+
The generic ``leds`` example from ``nuttx-apps`` can be used to validate the
63+
LED interface.
64+
65+
Board Buttons
66+
-------------
67+
68+
No button is currently exposed by the board port.
69+
70+
Pin Mapping
71+
===========
72+
73+
The current port uses the following MCU pins:
74+
75+
===== ========== ==========
76+
Pin Signal Notes
77+
===== ========== ==========
78+
PA9 USART1_TX Default serial console TX
79+
PA10 USART1_RX Default serial console RX
80+
PD13 LED2 User LED, active-low
81+
PD14 LED3 User LED, active-low
82+
PD15 LED4 User LED, active-low
83+
===== ========== ==========
84+
85+
Flashing
86+
========
87+
88+
The board directory includes a helper script for flashing through Holtek's
89+
Windows OpenOCD package from a WSL-based development environment:
90+
91+
.. code-block:: console
92+
93+
$ ./boards/arm/ht32f491x3/esk32/tools/flash.sh
94+
95+
The script expects:
96+
97+
* ``nuttx.bin`` already generated in the ``nuttx`` directory
98+
* Holtek xPack OpenOCD installed under
99+
``C:\Program Files (x86)\Holtek HT32 Series\HT32-IDE\xPack\xpack-openocd-0.11.0-4``
100+
* an HT32-Link compatible debug connection
101+
* Holtek xPack OpenOCD can be installed together with the HT32 IDE, available
102+
from Holtek's website: `Holtek Downloads <https://www.holtek.com/page/index>`_
103+
104+
Useful options:
105+
106+
.. code-block:: console
107+
108+
$ ./boards/arm/ht32f491x3/esk32/tools/flash.sh --dry-run
109+
$ ./boards/arm/ht32f491x3/esk32/tools/flash.sh --device HT32F49163_100LQFP
110+
$ ./boards/arm/ht32f491x3/esk32/tools/flash.sh --openocd-root /mnt/c/path/to/openocd
111+
112+
Testing Notes
113+
=============
114+
115+
The following commands are useful for validating the current port:
116+
117+
.. code-block:: console
118+
119+
nsh> hello
120+
nsh> ostest
121+
nsh> dumpstack
122+
nsh> leds
123+
124+
When ``leds`` is executed, the example opens ``/dev/userleds`` and cycles
125+
through the LED bitmasks supported by the board.
126+
127+
Current Limitations
128+
===================
129+
130+
The current port is still intentionally small. In particular:
131+
132+
* only the ``nsh`` board configuration is maintained
133+
* only USART1 routing is described by the board port
134+
* LEDs are supported, but board buttons are not yet implemented
135+
* internal GPIO helpers exist, but there is not yet a board-level ``/dev/gpio``
136+
test interface in this port
137+
138+
Configurations
139+
==============
140+
141+
nsh
142+
---
143+
144+
This is the currently maintained configuration for the board. It provides a
145+
serial console with the NuttShell and mounts ``/bin`` and ``/proc`` during
146+
board bring-up.
147+
148+
Configure and build it from the ``nuttx`` directory:
149+
150+
.. code-block:: console
151+
152+
$ ./tools/configure.sh -l esk32:nsh
153+
$ make -j
154+
155+
After boot, a typical prompt looks like:
156+
157+
.. code-block:: console
158+
159+
NuttShell (NSH) NuttX-12.x.x
160+
nsh> ls /
161+
/:
162+
bin/
163+
dev/
164+
proc/
165+
166+
And the built-in applications can be listed with:
167+
168+
.. code-block:: console
169+
170+
nsh> ls /bin
171+
dd
172+
dumpstack
173+
hello
174+
leds
175+
nsh
176+
ostest
177+
sh

‎Documentation/platforms/arm/ht32f491x3/index.rst‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
===============
2+
Holtek HT32F491
3+
===============
4+
5+
The HT32F491x3 family is based on the ARM Cortex-M4 core.
6+
7+
Supported Boards
8+
================
9+
10+
.. toctree::
11+
:glob:
12+
:maxdepth: 1
13+
14+
boards/*/*

‎arch/arm/include/ht32f491x3/chip.h‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -56,10 +56,10 @@
5656
#define HT32_NGPIO 6
5757

5858
#define HT32_HICK_FREQUENCY 8000000
59-
#define HT32_HICK48_FREQUENCY 48000000
59+
#define HT32_HICK48_FREQUENCY 48000000
6060
#define HT32_HEXT_MIN_FREQUENCY 4000000
61-
#define HT32_HEXT_MAX_FREQUENCY 25000000
62-
#define HT32_PLL_MAX_FREQUENCY 150000000
61+
#define HT32_HEXT_MAX_FREQUENCY 25000000
62+
#define HT32_PLL_MAX_FREQUENCY 150000000
6363

6464
#define HT32_SYSCLK_FREQUENCY CONFIG_HT32F491X3_SYSCLK_FREQUENCY
6565
#define HT32_HCLK_FREQUENCY HT32_SYSCLK_FREQUENCY

0 commit comments

Comments
 (0)