modm-data tools
Answers about STM32 devices for embedded developers and their coding agents: a command line, an MCP server and a few interactive pages.
modm-data converts vendor sources (CMSIS headers,
SVD files, the STM32CubeMX database, PDF documentation) into a stable form in the ext/ folder
of its checkout. The modm-data tools only read that data.
They answer questions like these:
- Headers: which CMSIS header a device uses, which headers define a macro, which bus a peripheral is on.
- Registers: the bit fields of a peripheral, and what a value read from a board means.
- Documents: the datasheet, reference manual and errata of a device; search them, read a section or a table as Markdown.
- Figures: the labels of a drawing, a PNG of one region, the curves of a chart, the lanes of a timing diagram.
- Clocks: the clock tree, flash wait states, and a clock configuration for frequency targets with the modm
SystemClockcode. - Interrupts: which events share a vector, with their enable, flag and clear bits, and the trigger multiplexers between peripherals.
- Pins: the alternate functions of the device pins and the connector pins of NUCLEO boards and Discovery kits.
The same 25 lookups are available as the modm-data-lookup command and as
MCP tools. Every lookup takes text and returns text.
Installation
The tools
You need Python 3.11 or newer, git, and g++ and patch for modm-data.
The tools read the data in the ext/ folder of a modm-data checkout, so modm-data is installed
from that checkout with pip install -e, not from PyPI. Clone both repositories next to each other:
git clone https://github.com/modm-io/modm-data.git
git clone https://github.com/modm-ext/modm-data-tools.git
cd modm-data-tools
make venv
make venv creates .venv and installs both packages in editable mode:
python3 -m venv .venv
.venv/bin/pip install -e "../modm-data" -e ".[all]"
If modm-data is somewhere else, pass its path: make venv MODM_DATA=/path/to/modm-data.
The extra [all] includes the MCP server (mcp, uvicorn) and pytest.
This installs two commands into .venv/bin: modm-data-lookup and modm-data-mcp.
The data
All data goes into the ext/ folder of the modm-data checkout. Run these targets there,
with the virtual environment of the tools active (source ../modm-data-tools/.venv/bin/activate),
since they call python3 -m modm_data….
Public sources
make clone-sources-stmicro # headers, SVDs, CubeHAL, packs
make convert-stmicro-header-svd # SVDs from the CMSIS headers
The first target clones the CMSIS headers, the ST SVD files, the CubeHAL drivers, the CMSIS packs of ST and the CMSIS core, all public repositories under BSD-3-Clause and Apache-2.0.
Data you download and convert yourself
The STM32CubeMX database and ST's PDF documentation are under the ST licence agreement (SLA). They cannot be redistributed, so modm-data downloads them from ST for you and you convert them locally:
make download-stmicro-cubemx # CubeMX database from ST
make build-device-database # ext/modm-data/devices.db
make download-stmicro-pdfs # all PDFs, about 10 GB
make convert-stmicro-html # PDF to HTML, takes long
You can also convert only the documents you need, one PDF at a time:
# converts ext/stmicro/pdf/RM0440-v9.pdf
make ext/stmicro/html-archive/RM0440-v9
The conversion log goes to log/stmicro/html/. The first documentation lookup builds a SQLite
full-text index in ext/cache/lookup; it is rebuilt when the HTML archive or the CubeMX checkout
moves to another commit. The MCP server starts building it in the background when it starts.
What needs what
| Data | Needed by |
|---|---|
| CMSIS headers, header SVDs | SVD Registers and Peripheral Variants pages; together with devices.db: the header and register lookups |
devices.db (CubeMX) | every lookup that takes a device name: headers, registers, flash latency, pin functions, board pinouts |
| CubeMX database | clock trees and the clock solver, the documents of a device (device_docs), interrupts |
| HTML documentation | documents, figures, register descriptions, interrupts, interconnect, board pinouts |
With the public sources alone you get the SVD Registers and Peripheral Variants pages.
The lookups map part names like stm32g474re to headers through devices.db, so even the
header and register lookups need the CubeMX database. Documents, figures, clock trees and board pinouts
need the ST data as well.
Environment
The defaults work for the layout above. These variables override them:
| Variable | Default | Meaning |
|---|---|---|
MODM_DATA | the installed modm-data checkout | the checkout whose ext/ folder is read |
MODM_DOCS_ARCHIVE | ext/stmicro/html-archive | another HTML archive, for example a local conversion; it gets an index of its own |
MODM_DATA_LOOKUP_CACHE | ext/cache/lookup | the full-text index and the OCR results |
MODM_REPO | modm next to the modm-data checkout | the modm checkout that clock_solve --code generates the code for |
The text of bitmap figures (board photos) comes from the OCR of macOS. On other systems these figures have no text.
Command line
Usage
Every lookup is a subcommand of modm-data-lookup. Activate the virtual environment or call
.venv/bin/modm-data-lookup directly. --help lists all of them, and
modm-data-lookup <tool> --help shows the full description and the arguments of one:
modm-data-lookup --help
modm-data-lookup doc_section --help
usage: python -m modm_data_tools.lookup doc_section [-h]
[--subsections | --no-subsections]
[--offset OFFSET]
[--max_chars MAX_CHARS]
doc section
One section as Markdown, with its subsections unless `subsections` is false. Register layouts become one line
per bit field, large tables are only summarized (read them with doc_table). Long sections are paged by `offset`,
`max_chars` is at most 100000.
…
The arguments follow the parameters of the lookup functions:
- Required parameters are positional arguments:
doc_section RM0440 7.2.1. - Optional parameters are options with the same name, underscores included:
--max_chars 600. - Boolean parameters have a pair of flags:
--subsectionsand--no-subsections,--codeand--no-code,--imageand--no-image. - Patterns like
find_define'spatternordoc_table's--whereare regular expressions. A regex may run for 2 seconds on one text; a slower one is rejected withpattern too slow, simplify it, an invalid one withinvalid regex: …. - Lists are capped:
--limitis at most 200 and--max_charsat most 100000. Larger values are clamped. Long answers say how to get the rest, for example with--offset.
A wrong input prints a message to stderr and exits with 1. Anything else is a bug and prints a traceback.
modm-data-lookup device_header stm99
no STM32 device matches 'stm99', similar: stm32u599vjt6 stm32l4s9ziy6 stm32l4s9zit6 stm32l4s9zij6 stm32l4s9vit6
The examples below are real output, shortened where marked with ….
Headers
A device name is a prefix of the part name, so g474re and stm32g474ret6 both work.
modm-data-lookup device_header g474re
…/ext/stmicro/header/stm32g4xx/Include/stm32g474xx.h (3 devices: stm32g474ret3 stm32g474ret6 stm32g474ret7)
find_define answers which headers define a macro, matched as a full regex:
modm-data-lookup find_define 'FDCAN_CCCR_\w+' --devices g4 --limit 5
12 headers (338 devices) define it, 0 headers (0 devices) do not.
Defined in:
all of them: FDCAN_CCCR_ASM FDCAN_CCCR_ASM_Msk FDCAN_CCCR_ASM_Pos FDCAN_CCCR_BRSE FDCAN_CCCR_BRSE_Msk ... (+37)
stm32g411xb.h stm32g411xc.h stm32g414xx.h stm32g431xx.h stm32g441xx.h stm32g471xx.h stm32g473xx.h …
Related: header_devices lists the devices of a header, device_condition writes the
lbuild template condition for the devices that define a macro, peripheral_buses lists the bus of
every peripheral, and flash_latency the wait states per voltage:
modm-data-lookup flash_latency stm32g474re
…
1.28 V: 0 WS <= 34 MHz, 1 WS <= 68 MHz, 2 WS <= 102 MHz, 3 WS <= 136 MHz, 4 WS <= 170 MHz
1.2 V: 0 WS <= 30 MHz, 1 WS <= 60 MHz, 2 WS <= 90 MHz, 3 WS <= 120 MHz, 4 WS <= 150 MHz
1 V: 0 WS <= 12 MHz, 1 WS <= 24 MHz, 2 WS <= 26 MHz
Registers
The registers come from the SVD files generated from the CMSIS headers, plus the Cortex-M core peripherals
(SCB, NVIC, SysTick, …) from the CMSIS core headers. register_map shows all registers of a peripheral:
modm-data-lookup register_map stm32g474re USART1
stm32g474xx USART1 @ 0x40013800: Universal Synchronous Asynchronous Receiver Transmitter
0x40013800 +0x000 CR1: USART Control register 1
RXFFIE[31] TXFEIE[30] FIFOEN[29] M1[28] EOBIE[27] RTOIE[26] DEAT[25:21] DEDT[20:16] OVER8[15] CMIE[14] …
0x40013804 +0x004 CR2: USART Control register 2
…
decode_register decodes a value, for example one read with a debugger:
modm-data-lookup decode_register stm32g474re --register RCC.CR --value 0x03030500
RCC.CR @ 0x40021000: RCC clock control register = 0x03030500
25 PLLRDY = 0x1: System PLL clock ready
24 PLLON = 0x1: System PLL clock enable
17 HSERDY = 0x1: External High Speed oscillator (HSE) clock ready
16 HSEON = 0x1: External High Speed oscillator (HSE) clock enable
10 HSIRDY = 0x1: Internal High Speed oscillator (HSI16) clock ready flag
8 HSION = 0x1: Internal High Speed oscillator (HSI16) clock enable
(3 other fields are 0)
It also takes the output of OpenOCD's mdw as it is, then the register can be left out.
Bare numbers are hex, like mdw prints them:
modm-data-lookup decode_register stm32g474re --value '0x40021000: 03030500 00000000 00001002'
RCC.CR @ 0x40021000: RCC clock control register = 0x03030500
…
RCC.ICSCR @ 0x40021004: RCC internal clock sources calibration register = 0x00000000
RCC.CFGR @ 0x40021008: RCC clock configuration register = 0x00001002
13:11 PPRE2 = 0x2: PRE2[2:0] bits (APB2 prescaler)
10:8 PPRE1 = 0x0 DIV_1: PRE1[2:0] bits (APB2 prescaler)
7:4 HPRE = 0x0 DIV_1: HPRE[3:0] bits (AHB prescaler)
1:0 SW = 0x2 HSE: SW[1:0] bits (System clock Switch)
(3 other fields are 0)
Fault registers work the same way: decode_register stm32g474re --register SCB.CFSR --value 0x00008200
reports BFARVALID and PRECISERR.
Documents
Start with the documents of a device:
modm-data-lookup device_docs stm32g474re
1 ST part numbers: stm32g474re
ES0430 (Errata Sheets, ST v9.0, HTML v10.0): STM32G471xx/473xx/474xx/483xx/484xx device errata
DS12288 (Product Specifications, ST v6.0, HTML v6.0): Arm® Cortex®-M4 32-bit MCU+FPU, 170 MHz / 213 DMIPS, …
PM0214 (Programming Manuals, ST v10.0, HTML v11.0): STM32 Cortex®-M4 MCUs and MPUs programming manual
RM0440 (Reference Manuals, ST v9.0, HTML v9.0): STM32G4 series advanced Arm®-based 32-bit MCUs
not shown: 54 AN, 7 TN, 1 UM (use kinds)
Then find the content. doc_search is a full-text search where all words must match and
"…" is a phrase. It also lists matching figures:
modm-data-lookup doc_search '"wait states" HCLK' --device stm32g474re --limit 3
AN5094 4.5.1 Performance versus Vcore ranges [0.7k]: ...Zero **wait state**, if 0 < **HCLK** ≤ 24 MHz One …
RM0440 4.3.3 Read access latency [3.1k]: ...Number of **wait states** according to CPU clock (**HCLK**) frequency …
RM0440 5.3.3 Read access latency [3.1k]: ...Number of **wait states** according to CPU clock (**HCLK**) frequency …
figures (doc_figure reads them):
RM0440 Figure 69. Wait configuration waveforms (section 19.6.5): Memory transaction = burst of 4 half words …
…
doc_grep finds what a word search cannot, like identifiers with digits, and ranks sections by hits:
modm-data-lookup doc_grep 'TIM\d+_SMCR' --doc RM0440 --limit 3
12 hits in 9 sections of RM0440
RM0440 31.7.7 TIM15 capture/compare mode register 1 (TIM15_CCMR1): 2 hits, 0.6/1k chars: ...ly if an internal …
…
[6 more sections with 6 hits]
Navigate with doc_toc and read with doc_section. The size of each section tells
you what reading it costs:
modm-data-lookup doc_toc RM0440 --section 7 --depth 1
modm-data-lookup doc_section RM0440 7.2.1 --no-subsections --max_chars 600
RM0440 v9.0
7 Reset and clock control (RCC) [112k]
7.1 Reset [4.8k]
7.2 Clocks [23k]
7.3 Low-power modes [1.6k]
7.4 RCC registers [82k]
RM0440 v9.0 section 7.2.1
#### 7.2.1 HSE clock
The high speed external clock signal (HSE) can be generated from two possible clock sources:
…
[1106 more characters, continue with offset=519]
Tables are found by caption and column header with find_tables and read with doc_table,
which can keep only some columns and rows:
modm-data-lookup doc_table DS12288 13 --columns port,AF7 --where '^PA9$'
DS12288 v6.0 section 4.11
**Table 13. Alternate function**
| Port #1 | Port #2 | AF7 / USART1/2/3 /FDCAN/COMP7/5/6 |
|---|---|---|
| Port A | PA9 | USART1_TX |
doc_register gives the reference manual description of a register, with the address from the header SVD:
modm-data-lookup doc_register RCC_CR --device stm32g474re
Addresses (stm32g474xx header SVD): RCC.CR 0x40021000
…
**7.4.1 Clock control register (RCC_CR)**
Address offset: 0x00
Reset value: 0x0000 0500
…
Figures
doc_figures finds figures by a regex on the caption and the labels in the drawing:
modm-data-lookup doc_figures RM0440 --query 'clock tree'
RM0440 v9.0: 1 of 688 figures
Figure 17 (section 7.2): Clock tree
to IWDG | LSI RC 32 kHz | LSCO | to RTC | OSC32_OUT | LSE OSC | /32 | 32.768 kHz ... (96 labels)
doc_figure gives the labels by the cells of a 4×4 grid (columns A–D, rows 1–4). With --image
it writes a PNG of the figure, or only of a region, which is much smaller:
modm-data-lookup doc_figure RM0440 17
modm-data-lookup doc_figure RM0440 17 --image --region C2:D2 --output clock.png
RM0440 v9.0 section 7.2, Figure 17. Clock tree
96 labels by cell (A-D left to right, 1-4 top to bottom):
A1: LSI RC 32 kHz | LSCO | OSC32_OUT | LSE OSC | 32.768 kHz | OSC32_IN | LSE LSI | HSI HSE SYSCLK PLLCLK HSI48 | …
B1: /32
C1: AHB | HCLK | PRESC | / 1,2,..512 | / 8
…
RM0440 v9.0 section 7.2, Figure 17. Clock tree, region C2:D2, 468x304 px
written to clock.png
doc_figure_data reads the data from the geometry of the drawing: the curves of characteristic charts,
the lanes and timing parameters of timing diagrams, and state machines and flowcharts as Mermaid graphs.
The result says whether it was verified against the drawing.
modm-data-lookup doc_figure_data DS12288 18 --x 25,85
DS12288 v6.0 section 5.3.4, Figure 18. V REFINT versus temperature
chart, verified against the drawing
x: (no title), linear, -40 to 120
y: V, linear, 1.185 to 1.235
typical characterization data, not guaranteed values
curve Max: y(25) = 1.231, y(85) = 1.229
curve Mean: y(25) = 1.213, y(85) = 1.212
curve Min: y(25) = 1.195, y(85) = 1.196
Clocks
The clock lookups work on the clock tree of STM32CubeMX and take its part names, like STM32G474RETx.
clock_solve finds a configuration for frequency targets. Targets are exact (40M),
relative (49.152M~0.1%), a range (12.288M..12.3M), a bound (ADC<=50M)
or max. --config describes the board, --code adds the modm code:
modm-data-lookup clock_solve STM32G474RETx "SYSCLK=max, FDCAN1=40M" --config "HSE=24M" --code
STM32G474RETx: solved in 0.07 s
targets:
SysCLKOutput = 160 MHz (want max) ok from SysClkSource < PLLR < PLLN < PLLM < PLLSource < HSEOSC
FDCAN1 = 40 MHz (want 40 MHz) ok from FDCANMult < PLLQ < PLLN < PLLM < PLLSource < HSEOSC
clocks: SysCLK 160 MHz, FCLKCortex 160 MHz, AHB 160 MHz, APB1 160 MHz, APB2 160 MHz
power: PWR_Regulator_Voltage_Scale=PWR_REGULATOR_VOLTAGE_SCALE1_BOOST, flash FLASH_LATENCY_4
config: HSEOSC=24M, SysClkSource=PLLCLK, PLLSource=HSE, PLLM=3, PLLN=40, FDCANMult=PLL, PLLQ=8
next: pass this config back with more targets or use items; it keeps these choices where it can.
namespace Board
{
using namespace modm::literals;
/// STM32G474RETx, generated by the clock solver for the modm Rcc API
struct SystemClock
{
static constexpr uint32_t Hse = 24_MHz;
static constexpr uint32_t SysClk = 160_MHz;
…
static constexpr Rcc::PllConfig pll{
.M = 3,
.N = 40,
.R = 2,
.Q = 8
};
…
};
} // namespace Board
Work iteratively: solve the core first, then pass the returned config: line back as
--config with more targets. The solver keeps earlier choices where it can.
--code needs a modm checkout (see MODM_REPO).
clock_tree shows the tree. With --node it shows the path to a peripheral and the limits,
with --config the frequency of every node, the violated limits and the flash wait states:
modm-data-lookup clock_tree STM32G474RETx --node FDCAN1
STM32G474RETx: drawing STM32G4, RCC STM32G4_rcc_v1_0, 80 nodes, 67 peripherals
…
FDCAN1 peripheral <- FDCANoutput
from: FDCANoutput output <- FDCANMult; FDCANMult mux <- APB1Prescaler* | PLLQ | HSEOSC; APB1Prescaler div 1,2,4,8,16 …
bus: APB1Output output <- APB1Prescaler [<=170 MHz]
Interrupts
irq_events lists the interrupt vectors and the sources that name each instance. With --query
it shows the events of the matching vectors with their enable, flag and clear bits:
modm-data-lookup irq_events stm32g071rb --query TIM6_DAC
stm32g071rb: stm32g071xx.h, RM0444, ST SVD STM32G071.svd, 31 vectors, 305 events
17 TIM6_DAC_LPTIM1: DAC1[cubemx,name,rm], LPTIM1[cubemx,name,rm], TIM6[cubemx,name,rm,svd]
RM: TIM6, LPTIM1 and DAC global interrupt
CubeMX: TIM6, DAC1 and LPTIM1 interrupts (LPTIM1 interrupt through EXTI line 29)
DAC1 DMAUDR2: enable CR.DMAUDRIE2, flag SR.DMAUDR2, write 1 to the flag (no read-modify-write) [name,ll,rm-table,rm-register]
…
LPTIM1 DOWN: enable IER.DOWNIE, flag ISR.DOWN, write 1 to ICR.DOWNCF [name,ll,rm-register]
…
interconnect gives the trigger multiplexers between peripherals with the register value of each signal:
modm-data-lookup interconnect stm32g474re --sink TIM2 --signal TIM3_TRGO
stm32g474re: RM0440, 16 multiplexers
TIM2_TS @0x40000008 (bits 6:4 + bits 21:20): TIM3_TRGO=2
Pins
pin_functions takes a pin, or a regex on signal names to find the pins that can carry a signal:
modm-data-lookup pin_functions stm32g474re --query USART2_TX
stm32g474ret3 (also matches stm32g474ret6 stm32g474ret7)
USART2_TX: PA2 AF7, PA14 AF7, PB3 AF7
board_pinout reads the connector tables of the user manual of a NUCLEO board or Discovery kit.
--query takes words that must all match, for example a GPIO to find all its connector pins:
modm-data-lookup board_pinout nucleo-g474re --query PA9
NUCLEO-G474RE: UM2505-v7, device STM32G474RETx
CN5 (arduino):
CN5-1 D8: PA9, net ARD_D8, function I/O
CN10 (morpho, right):
CN10-21: PA9
MCP server
The MCP server offers the same lookups as tools to coding agents. All tools are read-only. There are two ways to run it.
Running it
stdio, one server per client: the client starts modm-data-mcp itself.
This server has an extra tool, reload_server, which reloads the code of the lookups after you
edit them, without reconnecting.
HTTP, one server shared by all clients:
make mcp # http://127.0.0.1:8765/mcp
This runs uvicorn with --reload, so the server restarts whenever the code of the tools
or of modm-data changes. It is stateless, so clients do not notice a restart. Use it when several agents
work at the same time: they share one index and one set of caches.
Claude Code
Over stdio, with the absolute path to your checkout:
claude mcp add --scope user modm-data -- /path/to/modm-data-tools/.venv/bin/modm-data-mcp
Over HTTP, with make mcp running:
claude mcp add --scope user --transport http modm-data http://127.0.0.1:8765/mcp
--scope user makes the server available in all your projects. Check it with claude mcp list.
Claude desktop
Add the server to claude_desktop_config.json (Settings → Developer → Edit Config) and restart the app:
{
"mcpServers": {
"modm-data": {
"command": "/path/to/modm-data-tools/.venv/bin/modm-data-mcp"
}
}
}
Add "env": {"MODM_DATA": "/path/to/modm-data"} next to command if the tools should read
another checkout than the installed one.
Apps
With the environment variable MODM_DATA_MCP_APPS=1 (off by default), decode_register and
clock_solve are also MCP Apps: hosts that
render apps show the decoded registers drawn like in the reference manual, and the active clock path of the solution
with a button for the whole tree (fullscreen where the host has it). The Claude desktop chat and claude.ai render
them, Claude Code does not. The model gets the same text either way, the data of the view travels in the
_meta of the result. In claude_desktop_config.json:
{
"mcpServers": {
"modm-data": {
"command": "/path/to/modm-data-tools/.venv/bin/modm-data-mcp",
"env": {"MODM_DATA_MCP_APPS": "1"}
}
}
}
The pages are the views of the web pages, bundled into one HTML file each time the host reads them, so edits in
web/ show up after reloading the MCP configuration. They load the ext-apps client from unpkg.com and
dagre from cdnjs.cloudflare.com, so they need a network connection.
Other clients
Any MCP client works. For stdio, the command is /path/to/modm-data-tools/.venv/bin/modm-data-mcp
without arguments. For HTTP, the endpoint is http://127.0.0.1:8765/mcp with the Streamable HTTP
transport. The server answers in JSON and refuses the optional GET stream with 405, as the specification allows.
Tools
The tool names and parameters are those of the command line. The descriptions below are shortened;
clients get the full text, which is also what modm-data-lookup <tool> --help shows.
The last column names the data each tool reads (see The data):
headers and SVD are public, devices.db is
built from the CubeMX database, CubeMX and docs are the
ST data you download yourself.
| Tool | What it answers | Data |
|---|---|---|
| Headers | ||
device_header | Header files of all devices whose part name starts with a prefix. | headers devices.db |
header_devices | All devices that use a device header, given as file name or define. | headers devices.db |
find_define | Which device headers define a macro matching a regex, and which do not. | headers devices.db |
device_condition | lbuild template condition for the devices whose header defines a macro. | headers devices.db |
peripheral_buses | Which bus (AHB1, APB2, …) every peripheral of a device is on. | headers devices.db |
flash_latency | Flash wait states: the highest HCLK frequency per number of wait states and voltage. | devices.db |
| Clocks | ||
clock_tree | The CubeMX clock tree with domains, limits, the clock of every peripheral and the frequencies of a configuration. | CubeMX |
clock_solve | A clock configuration for frequency targets, why it fails, and the modm SystemClock code. | CubeMX |
| Registers | ||
register_map | All registers of a peripheral instance with address, offset and bit fields. | SVD devices.db |
decode_register | The bit fields of a register, and the decoded fields of a value or of OpenOCD mdw output. | SVD devices.db |
| Documents | ||
device_docs | The documents ST lists for a device, with the latest version in the HTML archive. | CubeMX docs |
doc_search | Full-text search over all sections of the latest documents, and matching figures. | docs |
doc_grep | Where a regex occurs, as hits per section or chapter with their density. | docs |
doc_toc | The headings of a document or of one section, with the size of each section. | docs |
doc_section | One section as Markdown, paged for long sections. | docs |
find_tables | Search table and figure captions and column headers. | docs |
doc_table | One table as Markdown, filtered by columns and rows. | docs |
doc_register | The description of a register from the reference manual, with one row per bit field. | docs |
| Figures | ||
doc_figures | The figures of a document: number, section, caption and the first labels. | docs |
doc_figure | One figure: its labels by region of the drawing, or a PNG of it or of one region. | docs |
doc_figure_data | The data of a figure: chart curves, timing diagram lanes, state machines and flowcharts as Mermaid. | docs |
| Interrupts | ||
irq_events | Which events are ORed into which interrupt vector, with enable, flag and clear bits. | CubeMX docs |
interconnect | The trigger multiplexers between peripherals (timer ITR, DAC TSEL) with their values. | docs |
| Pins | ||
board_pinout | The connector pins of a NUCLEO board or Discovery kit, with the solder bridges. | docs devices.db |
pin_functions | The alternate function numbers of the device pins, and which pins can carry a signal. | devices.db |
doc_figure with image returns the PNG as an MCP image next to the text.
Errors
Errors are tool errors with a message, so the agent can react. A wrong input, like an unknown device, a value out of range or an invalid or too slow regex, returns the message alone:
Error executing tool device_header: no STM32 device matches 'stm99', similar: stm32u599vjt6 stm32l4s9ziy6 …
Anything else is a bug in the tools and the message starts with the exception type, for example
KeyError: …. Please report those.
Instructions
The server sends instructions to the agent when it connects. They say which tool answers what, for example:
- Use
device_header,header_devicesandfind_defineinstead of greppingmodm-data/ext. - Find documentation with
device_docs,doc_searchandfind_tables, navigate withdoc_toc, read withdoc_sectionanddoc_tableinstead of reading the HTML files. - Find figures with
doc_figures, read them withdoc_figure, and take a PNG of one region when the drawing matters. - Solve clocks iteratively: feed the
configline ofclock_solveback with more targets. - Use
doc_registerfor the manual's description,register_mapanddecode_registerfor addresses and values read from a board. - Over stdio, call
reload_serverafter editing the tools; the HTTP server restarts by itself.
The full text is in src/modm_data_tools/lookup/mcp.py.
Pages
The pages on data.modm.dev run in the browser on data that modm-data generated. They are plain HTML, CSS and JavaScript without a build step. Each page keeps its state in the URL hash, so copy the address to share what you see.
SVD Registers
SVD Registers browses the SVD files generated from the STM32 CMSIS headers, or any SVD file you
open or drop on the page. It shows peripherals, registers, bit fields and enumerated values as a table, or the address
space as a zoomable map. Filter the file list and the registers with regular expressions, like
^USART\d+$ or CR1\.(RE|TE), optionally in the descriptions too. The hash holds the file name.
Peripheral Variants
Peripheral Variants shows how many different implementations of each STM32 peripheral exist. The register maps of every peripheral instance of every device are merged into variants with a common core and optional features. Compare them by address (binary), by name (source) or with the descriptions aside (similar), and highlight the variants that one device uses. The hash holds the mode, the peripheral group and the variant.
Board Pinouts
Board Pinouts shows the connector pins of the NUCLEO boards and Discovery kits with their
alternate functions, grouped into sets of boards that are compatible on those pins. Search pins, functions, board uses
and solder bridges by regex, like ^SPI\d_SCK$|PA5, show only free or freeable pins, and choose whether
compatible means the same name, the same function or only the same position. Hover a pin for its details.
The hash holds the filters.
Pin Mapping
Pin Mapping has one page per device with the package drawing and a table of all pins and their signals. Search for a device on the index page. On a device page you assign signals to pins; Copy Share URL puts your assignment into the hash, and you can export and import it as JSON.
Clock Solver
Clock Solver draws the CubeMX clock tree of a device and runs the same solver as
clock_solve in the browser (with Pyodide). Set targets on the nodes, lock settings, start from the boot
configuration or the maximum performance, and copy the modm Rcc code. The hash holds the whole configuration,
and Export and Import save it as JSON.
Serving locally
To use or work on the pages, generate their data in the modm-data checkout and serve the pages on top of it:
make serve # http://127.0.0.1:8768, data from ../modm-data/docs/src
Pages in web/ take precedence over files in the data folder. python3 serve.py <data folder> [port]
serves another folder. In modm-data, make build-homepage generates the data of all pages into
docs/src. To generate the data of a single page, run its exporter from the modm-data checkout:
| Page | Data |
|---|---|
| SVD Registers | python -m modm_data.header2svd.stmicro --all --output docs/src/svd/ |
| Peripheral Variants | python -m modm_data.svd2variants --all --input docs/src/svd/ --output docs/src/variants/ |
| Board Pinouts | python -m modm_data.html2pinout --output docs/src/boards/nucleo.json --pinout docs/src/pinout |
| Pin Mapping | python -m modm_data.pinout --output docs/src/pinout --templates ../modm-data-tools/templates/pinout |
| Clock Solver | python -m modm_data.clocks --output docs/src/clocks, then
python -m modm_data_tools.clocks --output docs/src/clocks |
The second clock step adds the modm Rcc API of every device (from the modm checkout in
MODM_REPO) and copies the Python code that the page runs.
Licences
The code of the tools and the pages is under the Mozilla Public License 2.0.
The data keeps the licence of its source. The CMSIS headers and Open Pin Data are BSD-3-Clause, the ST SVD files are Apache-2.0. The STM32CubeMX database and ST's PDF documentation are under the ST licence agreement (SLA): modm-data does not redistribute them, you download them from ST yourself.
Data derived from STM32CubeMX is under the ST SLA and must not be published. This includes
devices.db, the clock trees and the board pinouts, and the output of clock_tree and
clock_solve. Keep it out of public repositories.
See the modm-data README for the licence of every input source.