Skip to content

Commit 9bf613f

Browse files
FelipeMdeOFelipeMdeO
committed
Documentation/ht32f491x3: add ESK32 board docs
Document the HT32F491x3 ESK32 board, build steps, flashing flow, and basic validation commands. Signed-off-by: Felipe Moura <moura.fmo@gmail.com>
1 parent 166197e commit 9bf613f

File tree

3 files changed

+187
-0
lines changed

3 files changed

+187
-0
lines changed

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

260 KB
Loading

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

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

‎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/*/*

0 commit comments

Comments
 (0)