# Curated data for AVR and STM32 devices
This repository contains tools for extracting data from vendor sources,
filtering and reformatting them into a vendor-independent format.
This data is used by [the modm project][modm-io] to generate
its Hardware Abstraction Layer (HAL), startup code and additional support tools.
Please have a look [at modm's platform modules][modm-platform] for examples on
how to use this data.
These tools and this data set is maintained and curated by
[@salkinium][] only at [modm-io/modm-devices][modm-devices].
It is licensed under the MPLv2 license.
Currently data for <!--devicecount-->4360<!--/devicecount--> devices is available.
Please open an issue or better yet a pull request for additional support.
<!--devicetable-->
| Family | Devices | Family | Devices | Family | Devices |
|:--------------|:--------|:--------------|:--------|:--------------|:--------|
| AT90 | 12 | ATMEGA | 352 | ATTINY | 148 |
| NRF52 | 7 | RP20 | 1 | SAMD1x/D2x/DAx| 322 |
| SAMD5x/E5x | 114 | SAME7x/S7x/V7x| 134 | SAMG5x | 12 |
| SAML2x | 82 | STM32C0 | 19 | STM32F0 | 169 |
| STM32F1 | 174 | STM32F2 | 71 | STM32F3 | 145 |
| STM32F4 | 354 | STM32F7 | 181 | STM32G0 | 262 |
| STM32G4 | 295 | STM32H5 | 70 | STM32H7 | 206 |
| STM32L0 | 354 | STM32L1 | 180 | STM32L4 | 418 |
| STM32L5 | 44 | STM32U5 | 174 | STM32WB | 36 |
| STM32WL | 24 |
<!--/devicetable-->
### TL;DR
```sh
git clone https://github.com/modm-io/modm-devices.git
cd modm-devices/tools/generator
# Generate STM32 device data
make generate-stm32
# Generate SAM device data
make generate-sam
# Generate AVR device data
make generate-avr
```
You need Python3 with lxml, jinja2, deepdiff and CppHeaderParser packages.
```sh
pip install lxml jinja2 deepdiff CppHeaderParser
```
### Background
The device data idea originally comes from [xpcc](http://xpcc.io), which is the
predecessor to modm. Around 2013 we wanted to remove some of the repetitive
steps for building a HAL for AVR and STM32 devices and we chose to extract some
common data and collapse some peripheral drivers into Jinja2 templates.
This eventually evolved from manually extracted device data to fully generated
device data as soon as we found machine readable data sources from vendors.
For AVRs, we use the Atmel Target Description Files and for STM32, we use
internal data extracted from the CubeMX code generator.
Thus the Device File Generator (DFG) was born. The DFG has been rewritten for
modm to make it more maintainable and flexible as well as handling edge cases
much better.
We've separated the device data from modm, so that it becomes easier for YOU
to use this data for your own purposes.
[I've written an blog post with all the details](http://blog.salkinium.com/modm-devices).
### Data quality
The quality of the resulting device data obviously depend heavily on the quality
of the input data. I reluctantly maintain [a manual patch list][patches] for the bugs I've
encountered in the vendor sources, that I don't want to write a fix for in the DFG.
I have sent some of these patches to a contact in ST, however, every new release
of CubeMX changes a lot of data and can reintroduce some of these bugs.
I don't have a contact at Atmel to send bug reports to.
In addition, the CubeMX and AVR data does not contain some very important
information, which has to be assembled manually from hundreds of datasheets and
is then injected into the DFG. This is extremely labor intensive.
Please be respectful in asking for more data: I do not like spending hours
upon hours copying this additional data out of datasheets. It's also much more
likely to introduce errors, so automating data extraction is much easier for me
to maintain. You may of course open an issue about wrong data, but I'd prefer if
you opened a pull request that fixes the problem in the DFG instead.
All fixes MUST BE REPRODUCIBLE by the DFG! This means you need to track down the
bug to either the raw vendor data (=> update the manual patches) or in the DFG
data pipeline (=> fix the DFG).
*DO NOT UNDER ANY CIRCUMSTANCES PUBLISH THE RAW DATA EXTRACTED FROM CUBEMX ANYWHERE!*
It is subject to ST's copyright and you are not allowed to distribute it!
### Data format
I initially wanted to format this data as [device trees][device-tree],
however, since it is so tied to the Linux kernel, there isn't (or wasn't) much
tool support available at the time (though now there is a Python parser in Zephyr),
so we wrote our own tree-based format, which we called "device files" since we're
so creative. It allows lossless overlaying of data trees to reduce the amount of
duplicate data noise which makes it easier to comprehend as a human.
I do not intend to standardize this **format**, it may change at any time for any
reason. This allows us maximum flexibility in encoding this complicated
device information. If you want to engage in format discussions, please consider
contributing to the device tree specification instead.
Since I may change this data format to accommodate new data, you should write your
**own formatter** of this data, so that you have much better control over what
your tools are expecting!
So, if you need this data in the form of a Device Tree, please write your own
data converter and maintain it yourself!
For modm we convert this format to a Python dictionary tree, for details see the
`DeviceFile` class in `tools/device/modm/device_file.py`.
[modm-talk-preview]: https://gist.githubusercontent.com/salkinium/43a303c61b5e15e9a91d34116ea5d07c/raw/ab836c051039421e7bb0875ec9cb93c2d3f76236/modm-devices.png
[modm-talk]: http://salkinium.com/talks/modm_embo17.pdf
[modm-platform]: https://github.com/modm-io/modm/tree/develop/src/modm/platform
[device-tree]: https://www.devicetree.org
[@salkinium]: http://github.com/salkinium
[modm-devices]: https://github.com/modm-io/modm-devices
[modm-io]: https://github.com/modm-io
[patches]: https://github.com/modm-io/modm-devices/tree/develop/tools/generator/raw-data-extractor/patches
Raw data
{
"_id": null,
"home_page": "https://github.com/modm-io/modm-devices",
"name": "modm-devices",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.5.0",
"maintainer_email": null,
"keywords": "modm lbuild modm-devices stm32 avr sam nrf",
"author": "Niklas Hauser",
"author_email": "niklas@salkinium.com",
"download_url": "https://files.pythonhosted.org/packages/59/4c/44444b640c8b1264eca03ba7ab60761d00bb6ac62c8fbda0e91259a81018/modm_devices-0.10.1.tar.gz",
"platform": null,
"description": "# Curated data for AVR and STM32 devices\n\nThis repository contains tools for extracting data from vendor sources,\nfiltering and reformatting them into a vendor-independent format.\n\nThis data is used by [the modm project][modm-io] to generate\nits Hardware Abstraction Layer (HAL), startup code and additional support tools.\nPlease have a look [at modm's platform modules][modm-platform] for examples on\nhow to use this data.\n\nThese tools and this data set is maintained and curated by\n[@salkinium][] only at [modm-io/modm-devices][modm-devices].\nIt is licensed under the MPLv2 license.\n\nCurrently data for <!--devicecount-->4360<!--/devicecount--> devices is available.\nPlease open an issue or better yet a pull request for additional support.\n\n<!--devicetable-->\n| Family | Devices | Family | Devices | Family | Devices |\n|:--------------|:--------|:--------------|:--------|:--------------|:--------|\n| AT90 | 12 | ATMEGA | 352 | ATTINY | 148 |\n| NRF52 | 7 | RP20 | 1 | SAMD1x/D2x/DAx| 322 |\n| SAMD5x/E5x | 114 | SAME7x/S7x/V7x| 134 | SAMG5x | 12 |\n| SAML2x | 82 | STM32C0 | 19 | STM32F0 | 169 |\n| STM32F1 | 174 | STM32F2 | 71 | STM32F3 | 145 |\n| STM32F4 | 354 | STM32F7 | 181 | STM32G0 | 262 |\n| STM32G4 | 295 | STM32H5 | 70 | STM32H7 | 206 |\n| STM32L0 | 354 | STM32L1 | 180 | STM32L4 | 418 |\n| STM32L5 | 44 | STM32U5 | 174 | STM32WB | 36 |\n| STM32WL | 24 |\n<!--/devicetable-->\n\n\n### TL;DR\n\n```sh\ngit clone https://github.com/modm-io/modm-devices.git\ncd modm-devices/tools/generator\n# Generate STM32 device data\nmake generate-stm32\n# Generate SAM device data\nmake generate-sam\n# Generate AVR device data\nmake generate-avr\n```\n\nYou need Python3 with lxml, jinja2, deepdiff and CppHeaderParser packages.\n\n```sh\npip install lxml jinja2 deepdiff CppHeaderParser\n```\n\n\n### Background\n\nThe device data idea originally comes from [xpcc](http://xpcc.io), which is the\npredecessor to modm. Around 2013 we wanted to remove some of the repetitive\nsteps for building a HAL for AVR and STM32 devices and we chose to extract some\ncommon data and collapse some peripheral drivers into Jinja2 templates.\n\nThis eventually evolved from manually extracted device data to fully generated\ndevice data as soon as we found machine readable data sources from vendors.\nFor AVRs, we use the Atmel Target Description Files and for STM32, we use\ninternal data extracted from the CubeMX code generator.\n\nThus the Device File Generator (DFG) was born. The DFG has been rewritten for\nmodm to make it more maintainable and flexible as well as handling edge cases\nmuch better.\n\nWe've separated the device data from modm, so that it becomes easier for YOU\nto use this data for your own purposes.\n[I've written an blog post with all the details](http://blog.salkinium.com/modm-devices).\n\n\n### Data quality\n\nThe quality of the resulting device data obviously depend heavily on the quality\nof the input data. I reluctantly maintain [a manual patch list][patches] for the bugs I've\nencountered in the vendor sources, that I don't want to write a fix for in the DFG.\nI have sent some of these patches to a contact in ST, however, every new release\nof CubeMX changes a lot of data and can reintroduce some of these bugs.\nI don't have a contact at Atmel to send bug reports to.\n\nIn addition, the CubeMX and AVR data does not contain some very important\ninformation, which has to be assembled manually from hundreds of datasheets and\nis then injected into the DFG. This is extremely labor intensive.\n\nPlease be respectful in asking for more data: I do not like spending hours\nupon hours copying this additional data out of datasheets. It's also much more\nlikely to introduce errors, so automating data extraction is much easier for me\nto maintain. You may of course open an issue about wrong data, but I'd prefer if\nyou opened a pull request that fixes the problem in the DFG instead.\n\nAll fixes MUST BE REPRODUCIBLE by the DFG! This means you need to track down the\nbug to either the raw vendor data (=> update the manual patches) or in the DFG\ndata pipeline (=> fix the DFG).\n\n*DO NOT UNDER ANY CIRCUMSTANCES PUBLISH THE RAW DATA EXTRACTED FROM CUBEMX ANYWHERE!*\nIt is subject to ST's copyright and you are not allowed to distribute it!\n\n\n### Data format\n\nI initially wanted to format this data as [device trees][device-tree],\nhowever, since it is so tied to the Linux kernel, there isn't (or wasn't) much\ntool support available at the time (though now there is a Python parser in Zephyr),\nso we wrote our own tree-based format, which we called \"device files\" since we're\nso creative. It allows lossless overlaying of data trees to reduce the amount of\nduplicate data noise which makes it easier to comprehend as a human.\n\nI do not intend to standardize this **format**, it may change at any time for any\nreason. This allows us maximum flexibility in encoding this complicated\ndevice information. If you want to engage in format discussions, please consider\ncontributing to the device tree specification instead.\n\nSince I may change this data format to accommodate new data, you should write your\n**own formatter** of this data, so that you have much better control over what\nyour tools are expecting!\nSo, if you need this data in the form of a Device Tree, please write your own\ndata converter and maintain it yourself!\n\nFor modm we convert this format to a Python dictionary tree, for details see the\n`DeviceFile` class in `tools/device/modm/device_file.py`.\n\n\n[modm-talk-preview]: https://gist.githubusercontent.com/salkinium/43a303c61b5e15e9a91d34116ea5d07c/raw/ab836c051039421e7bb0875ec9cb93c2d3f76236/modm-devices.png\n[modm-talk]: http://salkinium.com/talks/modm_embo17.pdf\n[modm-platform]: https://github.com/modm-io/modm/tree/develop/src/modm/platform\n[device-tree]: https://www.devicetree.org\n[@salkinium]: http://github.com/salkinium\n[modm-devices]: https://github.com/modm-io/modm-devices\n[modm-io]: https://github.com/modm-io\n[patches]: https://github.com/modm-io/modm-devices/tree/develop/tools/generator/raw-data-extractor/patches\n",
"bugtrack_url": null,
"license": "MPL-2.0",
"summary": "Curated data for AVR and ARM Cortex-M devices",
"version": "0.10.1",
"project_urls": {
"Homepage": "https://github.com/modm-io/modm-devices"
},
"split_keywords": [
"modm",
"lbuild",
"modm-devices",
"stm32",
"avr",
"sam",
"nrf"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "fe00e3d98c90867acc6a8949e133c0eedcfa3175e0ea4c6abb31a45e050083d7",
"md5": "286862d34d9c00bbf286023b8772598a",
"sha256": "c8be6a6791bd736b67d12024a15912dd3145d249a9aaf97ec51e1b9a6cb2849a"
},
"downloads": -1,
"filename": "modm_devices-0.10.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "286862d34d9c00bbf286023b8772598a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.5.0",
"size": 1134935,
"upload_time": "2024-04-30T20:45:55",
"upload_time_iso_8601": "2024-04-30T20:45:55.285639Z",
"url": "https://files.pythonhosted.org/packages/fe/00/e3d98c90867acc6a8949e133c0eedcfa3175e0ea4c6abb31a45e050083d7/modm_devices-0.10.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "594c44444b640c8b1264eca03ba7ab60761d00bb6ac62c8fbda0e91259a81018",
"md5": "ae2b5c60b760a3a3d47f3f30e3bfbdfe",
"sha256": "21a4b3721e2ccaf6ea5c3eca40d904e481a2ee4ad433040bd4bfcac2af65f59d"
},
"downloads": -1,
"filename": "modm_devices-0.10.1.tar.gz",
"has_sig": false,
"md5_digest": "ae2b5c60b760a3a3d47f3f30e3bfbdfe",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.5.0",
"size": 981522,
"upload_time": "2024-04-30T20:45:56",
"upload_time_iso_8601": "2024-04-30T20:45:56.931930Z",
"url": "https://files.pythonhosted.org/packages/59/4c/44444b640c8b1264eca03ba7ab60761d00bb6ac62c8fbda0e91259a81018/modm_devices-0.10.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-30 20:45:56",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "modm-io",
"github_project": "modm-devices",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "modm-devices"
}
JSON
