├── _config.yml
├── .vscode
    └── settings.json
├── .gitmodules
├── .gitignore
├── .clang-format
├── uf2tool
    ├── Makefile
    └── tool.c
├── LICENSE.txt
├── utils
    ├── uf2conv.c
    ├── uf2conv.md
    ├── uf2families.json
    └── uf2conv.py
├── patcher
    ├── index.html
    ├── web.js
    └── patcher.js
├── uf2.h
├── SECURITY.md
├── cf2.md
├── hf2.md
└── README.md


/_config.yml:
--------------------------------------------------------------------------------
1 | theme: jekyll-theme-cayman


--------------------------------------------------------------------------------
/.vscode/settings.json:
--------------------------------------------------------------------------------
1 | {
2 |     "files.associations": {}
3 | }


--------------------------------------------------------------------------------
/.gitmodules:
--------------------------------------------------------------------------------
1 | [submodule "hidapi"]
2 | 	path = hidapi
3 | 	url = ../../signal11/hidapi
4 | 


--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
1 | tmp
2 | *.sw?
3 | flash.uf2
4 | flash.bin
5 | 
6 | built/
7 | uf2tool/uf2hid.h
8 | 


--------------------------------------------------------------------------------
/.clang-format:
--------------------------------------------------------------------------------
1 | BasedOnStyle: LLVM
2 | IndentWidth: 4
3 | UseTab: Never
4 | ColumnLimit: 100
5 | 


--------------------------------------------------------------------------------
/uf2tool/Makefile:
--------------------------------------------------------------------------------
1 | all:
2 | 	mkdir -p ../built
3 | 	$(CC) -g -Wall tool.c ../hidapi/mac/hid.c -I../../uf2-samd21/inc -I../hidapi/hidapi -I. -framework IOKit -framework CoreFoundation -o ../built/uf2tool
4 | 


--------------------------------------------------------------------------------
/LICENSE.txt:
--------------------------------------------------------------------------------
 1 | Microsoft UF2
 2 | 
 3 | The MIT License (MIT)
 4 | 
 5 | Copyright (c) Microsoft Corporation
 6 | 
 7 | All rights reserved.
 8 | 
 9 | Permission is hereby granted, free of charge, to any person obtaining a copy
10 | of this software and associated documentation files (the "Software"), to deal
11 | in the Software without restriction, including without limitation the rights
12 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
13 | copies of the Software, and to permit persons to whom the Software is
14 | furnished to do so, subject to the following conditions:
15 | 
16 | The above copyright notice and this permission notice shall be included in all
17 | copies or substantial portions of the Software.
18 | 
19 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
20 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
21 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
22 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
23 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
24 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
25 | SOFTWARE.
26 | 


--------------------------------------------------------------------------------
/utils/uf2conv.c:
--------------------------------------------------------------------------------
 1 | #include <stdio.h>
 2 | #include <string.h>
 3 | #include "uf2format.h"
 4 | 
 5 | int main(int argc, char **argv) {
 6 |     if (argc < 2) {
 7 |         fprintf(stderr, "USAGE: %s file.bin [file.uf2]\n", argv[0]);
 8 |         return 1;
 9 |     }
10 |     FILE *f = fopen(argv[1], "rb");
11 |     if (!f) {
12 |         fprintf(stderr, "No such file: %s\n", argv[1]);
13 |         return 1;
14 |     }
15 | 
16 |     fseek(f, 0L, SEEK_END);
17 |     uint32_t sz = ftell(f);
18 |     fseek(f, 0L, SEEK_SET);
19 | 
20 |     const char *outname = argc > 2 ? argv[2] : "flash.uf2";
21 | 
22 |     FILE *fout = fopen(outname, "wb");
23 | 
24 |     UF2_Block bl;
25 |     memset(&bl, 0, sizeof(bl));
26 | 
27 |     bl.magicStart0 = UF2_MAGIC_START0;
28 |     bl.magicStart1 = UF2_MAGIC_START1;
29 |     bl.magicEnd = UF2_MAGIC_END;
30 |     bl.targetAddr = APP_START_ADDRESS;
31 |     bl.numBlocks = (sz + 255) / 256;
32 |     bl.payloadSize = 256;
33 |     int numbl = 0;
34 |     while (fread(bl.data, 1, bl.payloadSize, f)) {
35 |         bl.blockNo = numbl++;
36 |         fwrite(&bl, 1, sizeof(bl), fout);
37 |         bl.targetAddr += bl.payloadSize;
38 |         // clear for next iteration, in case we get a short read
39 |         memset(bl.data, 0, sizeof(bl.data));
40 |     }
41 |     fclose(fout);
42 |     fclose(f);
43 |     printf("Wrote %d blocks to %s\n", numbl, outname);
44 |     return 0;
45 | }


--------------------------------------------------------------------------------
/utils/uf2conv.md:
--------------------------------------------------------------------------------
 1 | # uf2conv -- Packing and unpacking UF2 files
 2 | 
 3 | ## SYNOPSIS
 4 | 
 5 | **uf2conv.py** [-h] [-l]
 6 | 
 7 | **uf2conv.py** [-b BASE] [-f FAMILY] [-o FILE] [-d DEVICE_PATH] [-l] [-c] [-D]
 8 |                [-w] [-C]
 9 |                [HEX or BIN FILE]
10 | 
11 | **uf2conv.py** [-c] [-D] [-w] [-i] [UF2 FILE]
12 | 
13 | ## DESCRIPTION
14 | 
15 | ## EXAMPLES
16 | 
17 | ### Pack a .bin/.hex to .uf2
18 | 
19 | ```uf2conv.py cpx/firmware.bin --convert --output cpx/firmware.uf2```
20 | 
21 | ```uf2conv.py metro_m4/firmware.bin --base 0x4000 --convert --output metro_m4/firmware.uf2```
22 | 
23 | ```uf2conv.py nrf52840_xxaa.hex --family 0xADA52840 --convert --output nrf52840_xxaa.uf2```
24 | 
25 | ### Unpack a .uf2 to .bin
26 | 
27 | ```uf2conv.py current.uf2 --convert --output current.bin```
28 | 
29 | ## OPTIONS
30 | `-b`
31 | `--base`
32 | : set base address of application for BIN format (default: 0x2000)
33 | 
34 | `-f`
35 | `--family`
36 | : specify familyID - number or name (default: 0x0)
37 | 
38 | `-o`
39 | `--output`
40 | : write output to named file (defaults to "flash.uf2" or "flash.bin" where sensible)
41 | 
42 | `-d`
43 | `--device`
44 | : select a device path to flash
45 | 
46 | `-l`
47 | `--list`
48 | : list connected devices
49 | 
50 | `-c`
51 | `--convert`
52 | : do not flash, just convert
53 | 
54 | `-D`
55 | `--deploy`
56 | : just flash, do not convert
57 | 
58 | `-w`
59 | `--wait`
60 | : wait for device to flash
61 | 
62 | `-C`
63 | `--carray`
64 | : convert binary file to a C array, not UF2
65 | 
66 | `-i`
67 | `--info`
68 | : display header information from UF2, do not convert
69 | 


--------------------------------------------------------------------------------
/patcher/index.html:
--------------------------------------------------------------------------------
 1 | <!DOCTYPE html>
 2 | <html lang="en-US">
 3 | 
 4 | <head>
 5 |   <meta charset="UTF-8">
 6 | 
 7 |   <title>CF2 binary patcher</title>
 8 | 
 9 |   <meta name="viewport" content="width=device-width, initial-scale=1">
10 |   <meta name="theme-color" content="#157878">
11 |   <link rel="stylesheet" href="https://microsoft.github.io/uf2/assets/css/style.css">
12 |   <script src="patcher.js"></script>
13 |   <script src="web.js"></script>
14 |   <style>
15 |     #patch {
16 |       font-family: Consolas, "Liberation Mono", Menlo, Courier, monospace;
17 |       font-size: 0.9rem;
18 |       width: 100%;
19 |       height: 12em;
20 |     }
21 | 
22 |     .page-header {
23 |       padding: 2rem 2rem !important;
24 |     }
25 | 
26 |     .btn-dl,
27 |     .btn-dl:hover {
28 |       background-color: green;
29 |       float: right;
30 |       color: white;
31 |     }
32 | 
33 |     footer {
34 |       text-align: center;
35 |       margin-top: 5em;
36 |     }
37 |     footer a {
38 |       margin-right: 2em;
39 |     }
40 |   </style>
41 | </head>
42 | 
43 | <body ondrop="dropHandler(event);" ondragover="dragOverHandler(event);">
44 |   <section class="page-header">
45 |     <h1 class="project-name">CF2 patcher</h1>
46 |   </section>
47 | 
48 |   <section class="main-content">
49 |     <h2>Your patch</h2>
50 |     <textarea id="patch" spellcheck=false onchange="savePatch(event);"></textarea>
51 |     <a href="#" id="apply" class="btn btn-dl">Apply my patch</a>
52 | 
53 |     <h2>Information</h2>
54 |     <pre><code id="currconfig">Drop UF2 or BIN file above to see its config.</code></pre>
55 | 
56 |     <p>
57 |       <a href="https://github.com/Microsoft/uf2/blob/master/cf2.md">Learn more</a>
58 |       or
59 |       <a href="#" onclick="defines()">download configkeys.h</a>.
60 |     </p>
61 | 
62 |     <p>
63 |       <a href="#" id="rnd">Generate random number</a>
64 |       <span id="rnd-res"></span>
65 |     </p>
66 | 
67 | 
68 |   <footer>
69 |     <a href="https://makecode.com/privacy" target="_blank" rel="noopener">Privacy &amp; Cookies</a>
70 |     <a href="https://makecode.com/termsofuse" target="_blank" rel="noopener"> Terms Of Use</a>
71 |     <a href="https://makecode.com/trademarks" target="_blank" rel="noopener">Trademarks</a>
72 |     <span>© 2019 Microsoft</span>
73 |   </footer>
74 | 
75 |   </section>
76 | 
77 |   <script>
78 |     restorePatch()
79 |   </script>
80 | 
81 | </body>
82 | 
83 | </html>


--------------------------------------------------------------------------------
/uf2.h:
--------------------------------------------------------------------------------
 1 | /**
 2 | 
 3 | Microsoft UF2
 4 | 
 5 | The MIT License (MIT)
 6 | 
 7 | Copyright (c) Microsoft Corporation
 8 | 
 9 | All rights reserved.
10 | 
11 | Permission is hereby granted, free of charge, to any person obtaining a copy
12 | of this software and associated documentation files (the "Software"), to deal
13 | in the Software without restriction, including without limitation the rights
14 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
15 | copies of the Software, and to permit persons to whom the Software is
16 | furnished to do so, subject to the following conditions:
17 | 
18 | The above copyright notice and this permission notice shall be included in all
19 | copies or substantial portions of the Software.
20 | 
21 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
22 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
23 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
24 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
25 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
26 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
27 | SOFTWARE.
28 | 
29 | */
30 | #ifndef UF2FORMAT_H
31 | #define UF2FORMAT_H 1
32 | 
33 | #include <stdint.h>
34 | #include <stdbool.h>
35 | 
36 | // All entries are little endian.
37 | 
38 | #define UF2_MAGIC_START0 0x0A324655UL // "UF2\n"
39 | #define UF2_MAGIC_START1 0x9E5D5157UL // Randomly selected
40 | #define UF2_MAGIC_END 0x0AB16F30UL    // Ditto
41 | 
42 | // If set, the block is "comment" and should not be flashed to the device
43 | #define UF2_FLAG_NOFLASH        0x00000001
44 | #define UF2_FLAG_FILECONTAINER  0x00001000 // fle container
45 | #define UF2_FLAG_FAMILY_ID      0x00002000 // familyID present
46 | #define UF2_FLAG_MD5_CHKSUM     0x00004000 // MD5 checksum present
47 | #define UF2_FLAG_EXTENSION_TAGS 0x00008000 // extension tags present
48 | 
49 | typedef struct {
50 |     // 32 byte header
51 |     uint32_t magicStart0;
52 |     uint32_t magicStart1;
53 |     uint32_t flags;
54 |     uint32_t targetAddr;
55 |     uint32_t payloadSize;
56 |     uint32_t blockNo;
57 |     uint32_t numBlocks;
58 |     uint32_t reserved;
59 | 
60 |     // raw data;
61 |     uint8_t data[476];
62 | 
63 |     // store magic also at the end to limit damage from partial block reads
64 |     uint32_t magicEnd;
65 | } UF2_Block;
66 | 
67 | #endif
68 | 


--------------------------------------------------------------------------------
/SECURITY.md:
--------------------------------------------------------------------------------
 1 | <!-- BEGIN MICROSOFT SECURITY.MD V0.0.7 BLOCK -->
 2 | 
 3 | ## Security
 4 | 
 5 | Microsoft takes the security of our software products and services seriously, which includes all source code repositories managed through our GitHub organizations, which include [Microsoft](https://github.com/Microsoft), [Azure](https://github.com/Azure), [DotNet](https://github.com/dotnet), [AspNet](https://github.com/aspnet), [Xamarin](https://github.com/xamarin), and [our GitHub organizations](https://opensource.microsoft.com/).
 6 | 
 7 | If you believe you have found a security vulnerability in any Microsoft-owned repository that meets [Microsoft's definition of a security vulnerability](https://aka.ms/opensource/security/definition), please report it to us as described below.
 8 | 
 9 | ## Reporting Security Issues
10 | 
11 | **Please do not report security vulnerabilities through public GitHub issues.**
12 | 
13 | Instead, please report them to the Microsoft Security Response Center (MSRC) at [https://msrc.microsoft.com/create-report](https://aka.ms/opensource/security/create-report).
14 | 
15 | If you prefer to submit without logging in, send email to [secure@microsoft.com](mailto:secure@microsoft.com).  If possible, encrypt your message with our PGP key; please download it from the [Microsoft Security Response Center PGP Key page](https://aka.ms/opensource/security/pgpkey).
16 | 
17 | You should receive a response within 24 hours. If for some reason you do not, please follow up via email to ensure we received your original message. Additional information can be found at [microsoft.com/msrc](https://aka.ms/opensource/security/msrc). 
18 | 
19 | Please include the requested information listed below (as much as you can provide) to help us better understand the nature and scope of the possible issue:
20 | 
21 |   * Type of issue (e.g. buffer overflow, SQL injection, cross-site scripting, etc.)
22 |   * Full paths of source file(s) related to the manifestation of the issue
23 |   * The location of the affected source code (tag/branch/commit or direct URL)
24 |   * Any special configuration required to reproduce the issue
25 |   * Step-by-step instructions to reproduce the issue
26 |   * Proof-of-concept or exploit code (if possible)
27 |   * Impact of the issue, including how an attacker might exploit the issue
28 | 
29 | This information will help us triage your report more quickly.
30 | 
31 | If you are reporting for a bug bounty, more complete reports can contribute to a higher bounty award. Please visit our [Microsoft Bug Bounty Program](https://aka.ms/opensource/security/bounty) page for more details about our active programs.
32 | 
33 | ## Preferred Languages
34 | 
35 | We prefer all communications to be in English.
36 | 
37 | ## Policy
38 | 
39 | Microsoft follows the principle of [Coordinated Vulnerability Disclosure](https://aka.ms/opensource/security/cvd).
40 | 
41 | <!-- END MICROSOFT SECURITY.MD BLOCK -->
42 | 


--------------------------------------------------------------------------------
/patcher/web.js:
--------------------------------------------------------------------------------
  1 | "use strict";
  2 | 
  3 | function savePatch(ev) {
  4 |     let text = document.getElementById("patch")
  5 |     localStorage["UF2_PATCH"] = text.value
  6 | }
  7 | 
  8 | function genRnd(ev) {
  9 |     ev.preventDefault()
 10 |     let vals = new Uint32Array(1)
 11 |     window.crypto.getRandomValues(vals)
 12 |     document.getElementById("rnd-res").textContent = "Random number: 0x" + 
 13 |         ("000000000" + vals[0].toString(16)).slice(-8)
 14 | }
 15 | 
 16 | function restorePatch() {
 17 |     let text = document.getElementById("patch")
 18 |     text.value = localStorage["UF2_PATCH"] || ""
 19 |     document.getElementById("apply").onclick = applyPatch
 20 |     document.getElementById("rnd").onclick = genRnd
 21 | }
 22 | 
 23 | function download(buf, name) {
 24 |     let blob = new Blob([buf], {
 25 |         type: "application/x-uf2"
 26 |     });
 27 |     let url = URL.createObjectURL(blob);
 28 | 
 29 |     let a = document.createElement("a");
 30 |     document.body.appendChild(a);
 31 |     a.style = "display: none";
 32 |     a.href = url;
 33 |     a.download = name;
 34 |     a.click();
 35 |     window.URL.revokeObjectURL(url);
 36 | }
 37 | 
 38 | let currUF2 = null
 39 | let currUF2Name = ""
 40 | 
 41 | function showMSG() {
 42 |     if (infoMsg)
 43 |         document.getElementById("currconfig").textContent = infoMsg
 44 | }
 45 | 
 46 | function wrap(f) {
 47 |     try {
 48 |         infoMsg = ""
 49 |         f()
 50 |         showMSG()
 51 |     } catch (e) {
 52 |         log("Exception: " + e.message)
 53 |         showMSG()
 54 |     }
 55 | }
 56 | 
 57 | function defines() {
 58 |     download(configkeysH(), "configkeys.h")
 59 | }
 60 | 
 61 | function applyPatch() {
 62 |     wrap(() => {
 63 |         let text = document.getElementById("patch")
 64 |         let newcfg = text.value.trim()
 65 |         if (!currUF2)
 66 |             log("You have to drop a UF2 or BIN file with bootloader above before applying patches.")
 67 |         else if (!newcfg)
 68 |             log("You didn't give any patch to apply.")
 69 |         else {
 70 |             let buf = currUF2.slice()
 71 |             let r = patchConfig(buf, newcfg)
 72 |             if (!r.changes) {
 73 |                 log("No changes.")
 74 |             } else {
 75 |                 log("\nChanges:\n" + r.changes)
 76 |             }
 77 |             log("Downloading " + currUF2Name)
 78 |             download(r.patched, currUF2Name)
 79 |         }
 80 |     })
 81 | }
 82 | 
 83 | function dropHandler(ev) {
 84 |     ev.preventDefault();
 85 | 
 86 |     for (let i = 0; i < ev.dataTransfer.items.length; i++) {
 87 |         if (ev.dataTransfer.items[i].kind === 'file') {
 88 |             let file = ev.dataTransfer.items[i].getAsFile();
 89 |             let reader = new FileReader();
 90 |             infoMsg = ""
 91 |             reader.onload = e => {
 92 |                 wrap(() => {
 93 |                     let buf = new Uint8Array(reader.result)
 94 |                     let cfg = readConfig(buf)
 95 |                     currUF2 = buf
 96 |                     infoMsg += "\n" + cfg
 97 |                     currUF2Name = file.name
 98 |                 })
 99 |             }
100 |             reader.readAsArrayBuffer(file);
101 |             break
102 |         }
103 |     }
104 | }
105 | 
106 | function dragOverHandler(ev) {
107 |     ev.preventDefault();
108 |     ev.dataTransfer.dropEffect = 'copy';
109 | }


--------------------------------------------------------------------------------
/cf2.md:
--------------------------------------------------------------------------------
  1 | # Binary Bootloader-embedded Config (CF2)
  2 | 
  3 | ## Motivation
  4 | 
  5 | The goal of CF2 is to run the same binary on a number of devices with different
  6 | peripheral configuration, but the same MCU.
  7 | Typically, this has been achieved by embedding identification components in hardware
  8 | (eg. connecting certain MCU pins to GND or 3V) and having the firmware dynamically
  9 | detect these.
 10 | While simple, this only allows a few bits of configuration data to be stored on device.
 11 | 
 12 | Instead, we use the bootloader area for storing device specific configuration data.
 13 | Such data is not altered when the device is programmed with new firmware,
 14 | and the said firmware can refer to the configuration data in the bootloader area to
 15 | alter its behavior.
 16 | 
 17 | For example, MakeCode Arcade requires a device with 7 buttons (directions, A, B, and MENU),
 18 | a screen from a specific family, and one of the few supported accelerometers.
 19 | The exact configuration depends on the manufacturer, but the binary produced by MakeCode
 20 | will work on any device with the right MCU, provided it has the right configuration
 21 | data in the bootloader area.
 22 | 
 23 | Thus, the user only needs to select the type of MCU (which is color coded, 
 24 | and is assigned a simple user-facing name), and the resulting binary will work
 25 | on their device.
 26 | Moreover, they can drag the UF2 file between devices, provided they run the same MCU.
 27 | Once bootloaders are updated with networking support (wired or wireless), one device with 
 28 | a given MCU will be able to flash another.
 29 | 
 30 | ## Configuration data format
 31 | 
 32 | Data comes as pairs of 32 bit unsigned integers (in machine byte order).
 33 | * first pair is `0x1e9e10f1, 0x20227a79`
 34 | * second pair consists of the number of configuration entries, and a zero (reserved)
 35 | * then configuration entries follow, where the first element is the configuration
 36 |   entry key number, and the second is the value (these entries are sorted by key number)
 37 | * finally, a number of zeroes follows (typically at least a few hundred), 
 38 |   to store any additional configuration data in future
 39 | 
 40 | The file `configkeys.h` with definitions of key names can be downloaded from the 
 41 | patcher website (see below).
 42 | 
 43 | If you require your own key names, please use 
 44 | [random large key names](https://github.com/Microsoft/uf2#picking-numbers-at-random).
 45 | 
 46 | ## The Patcher
 47 | 
 48 | At https://microsoft.github.io/uf2/patcher/ we provide a tool, which given a UF2 or BIN file
 49 | and a configuration definition, binary-patches the UF2/BIN file and lets the user download it.
 50 | The tool also parses existing configuration information from the UF2/BIN file to show it.
 51 | 
 52 | Such tool is to be used by makers of devices.
 53 | For example, for MakeCode Arcade, this includes both factories and users who take an existing
 54 | multi-purpose board and connect keys and screen.
 55 | Such user would then download generic MakeCode Arcade bootloader (either a UF2 file,
 56 | which upgrades the bootloader, or a .BIN file with the bootloader) for the given MCU,
 57 | and binary patch it with their configuration.
 58 | Then, they would update the bootloader, and have a Arcade-compatible device.
 59 | 
 60 | ## Configuration file syntax
 61 | 
 62 | Example:
 63 | 
 64 | ```bash
 65 | # This is comment, which is ignored
 66 | // this is also a comment
 67 | 
 68 | # Configuration values for display registers and size
 69 | DISPLAY_CFG0 = 0x80
 70 | DISPLAY_CFG1 = 0x603
 71 | DISPLAY_CFG2 = 0x16
 72 | DISPLAY_HEIGHT = 128
 73 | DISPLAY_WIDTH = 160
 74 | 
 75 | PINS_PORT_SIZE = PA_32 # see below
 76 | 
 77 | # pin headers (if any)
 78 | PIN_A0 = PA02
 79 | PIN_A1 = PA05
 80 | PIN_A2 = PB08
 81 | PIN_D2 = PA07
 82 | PIN_D3 = PB22
 83 | PIN_SCK = PA01
 84 | PIN_MISO = PB23
 85 | PIN_MOSI = PA00
 86 | 
 87 | # pin functions
 88 | PIN_BTN_LEFT = PIN_D2        # use pin header name
 89 | PIN_BTN_UP = PB13            # use pin directly
 90 | PIN_DISPLAY_CS = 18          # can even just use a number for the pin
 91 | PIN_DISPLAY_SCK = PIN_SCK
 92 | PIN_DISPLAY_MOSI = PIN_MOSI
 93 | 
 94 | # custom configuration keys
 95 | _679732427 = 123
 96 | _815320287 = 0x80192
 97 | 
 98 | # remove an existing config entry
 99 | PIN_BTN_MENU2 = null
100 | ```
101 | 
102 | The keys are either key names, or underscore followed by a decimal number.
103 | The values are numbers in either decimal or hexadecimal,
104 | references to other keys, or pin numbers.
105 | The way pin numbers are parsed depends on the `PINS_PORT_SIZE`:
106 | * `PA_16` - pins are `PA00`-`PA15`, `PB00-PB15`, ..., used on STM32
107 | * `PA_32` - pins are `PA00`-`PA31`, ... - used on Microchip ATSAMD
108 | * `P0_16` - pins are `P0_0`-`P0_15`, `P1_0-P1_15`, ... - not used?
109 | * `P0_32` - pins are `P0_0-P0_31`, ... - used on Nordic NRF
110 | * `0` or missing - pins are `P_0`, `P_1`, ..., `P_1000`
111 | 
112 | Certain keys (like `PINS_PORT_SIZE`) have a number of pre-defined values,
113 | which can be used instead of integers.
114 | 
115 | Because you're usually use this syntax to patch an existing configuration,
116 | you sometimes may want to remove an entry that's already there.
117 | To do that, use `null` as the value of the key.
118 | 
119 | For list of keys and predefined values, see `configkeys.h` which can be downloaded
120 | from the patcher website.
121 | 
122 | ## Running from node.js
123 | 
124 | The patcher tool can be also run from command line.
125 | Download [patcher.js](https://raw.githubusercontent.com/Microsoft/uf2/master/patcher/patcher.js)
126 | and run it with node. It will print out help.
127 | 


--------------------------------------------------------------------------------
/hf2.md:
--------------------------------------------------------------------------------
  1 | # HID Flashing Format
  2 | 
  3 | HF2 (HID Flashing Format) is a protocol and message format intended for
  4 | communication with embedded devices. Basic functions supported include:
  5 | 
  6 | * serial communication for `printf()` debugging etc.
  7 | * flashing (updating device firmware)
  8 | * debugger interfaces
  9 | 
 10 | It is optimized for packet formats, where packets are around 64 bytes long.
 11 | It will work for smaller packets, of at least a few bytes, or bigger
 12 | ones, but be less efficient.
 13 | 
 14 | In particular, it is suitable for running over USB HID (Human Interface Device),
 15 | which is widely supported in various operating systems without the need for kernel-space
 16 | drivers. It is also possible to run the protocol over a WebUSB link with either a single
 17 | interrupt endpoint or two bulk endpoints, as well as using just the control pipe,
 18 | allowing direct access from supported browsers. 
 19 | 
 20 | ## Raw message format
 21 | 
 22 | HF2 messages are composed of packets. Packets are up to 64 bytes long.
 23 | Messages sent from host to device and vice versa have the same basic format.
 24 | 
 25 | The first byte of each packet indicates:
 26 | * length of the remaining data (payload) in the packet, in the lower 6 bits, i.e., between 0 and 63 inclusive
 27 | * the type of the packet, in the two high bits.
 28 | 
 29 | | Bit 7 | Bit 6 | Hex  | Meaning
 30 | |-------|-------|------|----------------------------------------------
 31 | | 0     | 0     | 0x00 | Inner packet of a command message
 32 | | 0     | 1     | 0x40 | Final packet of a command message
 33 | | 1     | 0     | 0x80 | Serial `stdout`
 34 | | 1     | 1     | 0xC0 | Serial `stderr`
 35 | 
 36 | Serial messages are thus between 0 and 63 bytes in length.
 37 | 
 38 | Command messages can have any length (though devices will typically limit
 39 | it to the native flash page size + 64 bytes). They consist of a zero or more
 40 | inner packets, followed by a single final packet. Any of these packets
 41 | can carry between 0 and 63 bytes of payload.
 42 | 
 43 | For example:
 44 | 
 45 | ```
 46 | Packet 0: 83 01 02 03 AB FF FF FF
 47 | Packet 1: 85 04 05 06 07 08
 48 | Packet 2: 80 DE 42 42 42 42 FF FF
 49 | Packet 3: D0 09 0A 0B 0C 0D 0E 0F 10 11 12 13 14 15 16 17 FF FF FF
 50 | --->
 51 | Decoded: 01 02 03 04 05 06 07 08 D0 09 0A 0B 0C 0D 0E 0F 10 11 12 13 14 15 16 17
 52 | ```
 53 | 
 54 | Note that packets can be longer than the first byte requires (packets 0, 2, and 3 are).
 55 | The additional data should be discarded.
 56 | This is due to various HID implementations imposing an exact 64 byte packet size.
 57 | 
 58 | Different command messages cannot be interleaved.
 59 | 
 60 | Serial messages should not be interleaved with command messages (though it would be
 61 | technically possible).
 62 | 
 63 | ## Higher-level message format
 64 | 
 65 | ### Serial messages
 66 | 
 67 | Serial messages are meant for `printf()` style debugging
 68 | and general simple data output from the device.
 69 | If the device supports only one serial channel, it should support
 70 | the `stdout` channel. Otherwise, `stdout` is meant
 71 | for data output (eg., logging measurements), and `stderr`
 72 | is meant for `printf()` debugging.
 73 | 
 74 | The logging application on the host may choose to send these
 75 | two channels into a single output stream.
 76 | 
 77 | Serial messages contain between `0` and `63` bytes of payload data. 
 78 | Size of `0` can be used as a keep-alive packet if needed.
 79 | 
 80 | ### Command messages
 81 | 
 82 | Command structure:
 83 | 
 84 | ```c
 85 | struct Command {
 86 |     uint32_t command_id;
 87 |     uint16_t tag;
 88 |     uint8_t reserved0;
 89 |     uint8_t reserved1;
 90 |     uint8_t data[...];
 91 | };
 92 | 
 93 | struct Response {
 94 |     uint16_t tag;
 95 |     uint8_t status;
 96 |     uint8_t status_info;
 97 |     uint8_t data[...];
 98 | };
 99 | ```
100 | 
101 | All words in HF2 are little endian.
102 | 
103 | The `tag` is an arbitrary number set by the host, for example as sequence 
104 | number. The response should repeat the `tag`.
105 | 
106 | The two reserved bytes in the command should be sent as zero and ignored by the device.
107 | 
108 | The response status is one of the following:
109 | * `0x00` - command understood and executed correctly
110 | * `0x01` - command not understood
111 | * `0x02` - command execution error
112 | 
113 | Note, that embedded devices might crash on invalid arguments, instead
114 | of returning errors. OTOH, the devices should always handle invalid commands with
115 | `0x01` status.
116 | 
117 | In case of non-zero status, the `status_info` field can contain additional information.
118 | 
119 | The host shall not send a new command, until the previous one was responded to.
120 | TODO does this make sense? maybe just let USB flow control handle this?
121 | 
122 | ## Standard commands
123 | 
124 | Below we list standard commands. Not all commands have to be supported by all
125 | devices.
126 | 
127 | When the C fragment states `no results`, it means just a response
128 | with zero status and no additional data should be expected.
129 | 
130 | ### BININFO (0x0001)
131 | 
132 | This command states the current mode of the device:
133 | * ``mode == 0x01`` - bootloader, and thus flashing of user-space programs is allowed
134 | * ``mode == 0x02`` - user-space mode.
135 | It also returns the size of flash page size (flashing needs to be done on page-by-page basis),
136 | and the maximum size of message. It is always the case that 
137 | ``max_message_size >= flash_page_size + 64``.
138 | 
139 | ```c
140 | struct HF2_BININFO_Result {
141 |     uint32_t mode;
142 |     uint32_t flash_page_size;
143 |     uint32_t flash_num_pages;
144 |     uint32_t max_message_size;
145 |     uint32_t family_id; // optional
146 | };
147 | ```
148 | 
149 | ### INFO (0x0002)
150 | 
151 | Various device information. 
152 | The result is a character array. See `INFO_UF2.TXT` in UF2 format for details.
153 | 
154 | ```c
155 | // no arguments
156 | struct HF2_INFO_Result {
157 |     uint8_t info[...];
158 | };
159 | ```
160 | 
161 | 
162 | ### RESET INTO APP (0x0003)
163 | 
164 | Reset the device into user-space app. Usually, no response at all will arrive for this command.
165 | 
166 | ```c
167 | // no arguments, no result
168 | ```
169 | 
170 | 
171 | ### RESET INTO BOOTLOADER (0x0004)
172 | 
173 | Reset the device into bootloader, usually for flashing. Usually, no response at all will arrive for this command.
174 | 
175 | ```c
176 | // no arguments, no result
177 | ```
178 | 
179 | ### START FLASH (0x0005)
180 | 
181 | When issued in bootloader mode, it has no effect.
182 | In user-space mode it causes handover to bootloader.
183 | A `BININFO` command can be issued to verify that.
184 | 
185 | ```c
186 | // no arguments, no result
187 | ```
188 | 
189 | ### WRITE FLASH PAGE (0x0006)
190 | 
191 | Write a single page of flash memory.
192 | 
193 | ```c
194 | struct HF2_WRITE_FLASH_PAGE_Command {
195 |     uint32_t target_addr;
196 |     uint8_t data[flash_page_size];
197 | };
198 | // no result
199 | ```
200 | 
201 | ### CHKSUM PAGES (0x0007)
202 | 
203 | Compute checksum of a number of pages.
204 | Maximum value for ``num_pages`` is ``max_message_size / 2 - 2``.
205 | The checksum algorithm used is CRC-16-CCITT.
206 | 
207 | ```c
208 | struct HF2_CHKSUM_PAGES_Command {
209 |     uint32_t target_addr;
210 |     uint32_t num_pages;
211 | };
212 | struct HF2_CHKSUM_PAGES_Result {
213 |     uint16_t chksums[0 /* num_pages */];
214 | };
215 | ```
216 | 
217 | ### READ WORDS (0x0008)
218 | 
219 | Read a number of words from memory. 
220 | Memory is read word by word (and not byte by byte), and ``target_addr`` must
221 | be suitably aligned. This is to support reading of special IO regions.
222 | 
223 | ```c
224 | struct HF2_READ_WORDS_Command {
225 |     uint32_t target_addr;
226 |     uint32_t num_words;
227 | };
228 | struct HF2_READ_WORDS_Result {
229 |     uint32_t words[num_words];
230 | };
231 | ```
232 | 
233 | ### WRITE WORDS (0x0009)
234 | 
235 | Dual of READ WORDS, with the same constraints.
236 | 
237 | ```c
238 | struct HF2_WRITE_WORDS_Command {
239 |     uint32_t target_addr;
240 |     uint32_t num_words;
241 |     uint32_t words[num_words];
242 | };
243 | // no result
244 | ```
245 | 
246 | ### DMESG (0x0010)
247 | 
248 | Return internal log buffer if any.
249 | The result is a character array.
250 | 
251 | ```c
252 | // no arguments
253 | struct HF2_DMESG_Result {
254 |     uint8_t logs[...];
255 | };
256 | ```
257 | 
258 | 
259 | ## Extensibility
260 | 
261 | The HF2 protocol is easy to extend with new command messages.  The command ids
262 | you introduce should be chosen at random.  This ensures very low probability of
263 | conflict between different extensions.
264 | 
265 | While numbers like `0x42420123`, `0x10001`, or `0xdeaff00d` may look random,
266 | others are likely to use them as well and a conflict might occur.
267 | Please also do not use numbers below `0xffff`, as these are standardized here.
268 | Ideally, use one of the following commands (or similar) to generate a random number:
269 | 
270 | ```bash
271 | node -p "require('crypto').randomBytes(4).toString('hex')"
272 | # or slightly worse:
273 | printf "%04x%04x\n" $RANDOM $RANDOM
274 | ```
275 | 
276 | If you change the behavior of a command, even just extend what it can do, and
277 | there is even a remote possibility of devices or interface applications using
278 | it in the wild, it's best to introduce a new command, and possibly have the
279 | device handle both (fall-through `switch` cases are useful here).
280 | 
281 | ## Detection of HF2 devices
282 | 
283 | ## Notes
284 | 
285 | If the device exposes both HID and WebUSB, it has to use two separate
286 | interfaces. 
287 | 
288 | 


--------------------------------------------------------------------------------
/utils/uf2families.json:
--------------------------------------------------------------------------------
  1 | [
  2 |     {
  3 |         "id": "0x16573617",
  4 |         "short_name": "ATMEGA32",
  5 |         "description": "Microchip (Atmel) ATmega32"
  6 |     },
  7 |     {
  8 |         "id": "0x1851780a",
  9 |         "short_name": "SAML21",
 10 |         "description": "Microchip (Atmel) SAML21"
 11 |     },
 12 |     {
 13 |         "id": "0x1b57745f",
 14 |         "short_name": "NRF52",
 15 |         "description": "Nordic NRF52"
 16 |     },
 17 |     {
 18 |         "id": "0x1c5f21b0",
 19 |         "short_name": "ESP32",
 20 |         "description": "ESP32"
 21 |     },
 22 |     {
 23 |         "id": "0x1e1f432d",
 24 |         "short_name": "STM32L1",
 25 |         "description": "ST STM32L1xx"
 26 |     },
 27 |     {
 28 |         "id": "0x202e3a91",
 29 |         "short_name": "STM32L0",
 30 |         "description": "ST STM32L0xx"
 31 |     },
 32 |     {
 33 |         "id": "0x21460ff0",
 34 |         "short_name": "STM32WL",
 35 |         "description": "ST STM32WLxx"
 36 |     },
 37 |     {
 38 |         "id": "0x22e0d6fc",
 39 |         "short_name": "RTL8710B",
 40 |         "description": "Realtek AmebaZ RTL8710B"
 41 |     },
 42 |     {
 43 |         "id": "0x2abc77ec",
 44 |         "short_name": "LPC55",
 45 |         "description": "NXP LPC55xx"
 46 |     },
 47 |     {
 48 |         "id": "0x300f5633",
 49 |         "short_name": "STM32G0",
 50 |         "description": "ST STM32G0xx"
 51 |     },
 52 |     {
 53 |         "id": "0x31d228c6",
 54 |         "short_name": "GD32F350",
 55 |         "description": "GD32F350"
 56 |     },
 57 |     {
 58 |         "id": "0x3379CFE2",
 59 |         "short_name": "RTL8720D",
 60 |         "description": "Realtek AmebaD RTL8720D"
 61 |     },
 62 |     {
 63 |         "id": "0x04240bdf",
 64 |         "short_name": "STM32L5",
 65 |         "description": "ST STM32L5xx"
 66 |     },
 67 |     {
 68 |         "id": "0x4c71240a",
 69 |         "short_name": "STM32G4",
 70 |         "description": "ST STM32G4xx"
 71 |     },
 72 |     {
 73 |         "id": "0x4fb2d5bd",
 74 |         "short_name": "MIMXRT10XX",
 75 |         "description": "NXP i.MX RT10XX"
 76 |     },
 77 |     {
 78 |         "id": "0x51e903a8",
 79 |         "short_name": "XR809",
 80 |         "description": "Xradiotech 809"
 81 |     },
 82 |     {
 83 |         "id": "0x53b80f00",
 84 |         "short_name": "STM32F7",
 85 |         "description": "ST STM32F7xx"
 86 |     },
 87 |     {
 88 |         "id": "0x55114460",
 89 |         "short_name": "SAMD51",
 90 |         "description": "Microchip (Atmel) SAMD51"
 91 |     },
 92 |     {
 93 |         "id": "0x57755a57",
 94 |         "short_name": "STM32F4",
 95 |         "description": "ST STM32F4xx"
 96 |     },
 97 |     {
 98 |         "id": "0x5a18069b",
 99 |         "short_name": "FX2",
100 |         "description": "Cypress FX2"
101 |     },
102 |     {
103 |         "id": "0x5d1a0a2e",
104 |         "short_name": "STM32F2",
105 |         "description": "ST STM32F2xx"
106 |     },
107 |     {
108 |         "id": "0x5ee21072",
109 |         "short_name": "STM32F1",
110 |         "description": "ST STM32F103"
111 |     },
112 |     {
113 |         "id": "0x621e937a",
114 |         "short_name": "NRF52833",
115 |         "description": "Nordic NRF52833"
116 |     },
117 |     {
118 |         "id": "0x647824b6",
119 |         "short_name": "STM32F0",
120 |         "description": "ST STM32F0xx"
121 |     },
122 |     {
123 |         "id": "0x675a40b0",
124 |         "short_name": "BK7231U",
125 |         "description": "Beken 7231U/7231T"
126 |     },
127 |     {
128 |         "id": "0x68ed2b88",
129 |         "short_name": "SAMD21",
130 |         "description": "Microchip (Atmel) SAMD21"
131 |     },
132 |     {
133 |         "id": "0x6a82cc42",
134 |         "short_name": "BK7251",
135 |         "description": "Beken 7251/7252"
136 |     },
137 |     {
138 |         "id": "0x6b846188",
139 |         "short_name": "STM32F3",
140 |         "description": "ST STM32F3xx"
141 |     },
142 |     {
143 |         "id": "0x6d0922fa",
144 |         "short_name": "STM32F407",
145 |         "description": "ST STM32F407"
146 |     },
147 |     {
148 |         "id": "0x4e8f1c5d",
149 |         "short_name": "STM32H5",
150 |         "description": "ST STM32H5xx"
151 |     },
152 |     {
153 |         "id": "0x6db66082",
154 |         "short_name": "STM32H7",
155 |         "description": "ST STM32H7xx"
156 |     },
157 |     {
158 |         "id": "0x70d16653",
159 |         "short_name": "STM32WB",
160 |         "description": "ST STM32WBxx"
161 |     },
162 |     {
163 |         "id": "0x7b3ef230",
164 |         "short_name": "BK7231N",
165 |         "description": "Beken 7231N"
166 |     },
167 |     {
168 |         "id": "0x7eab61ed",
169 |         "short_name": "ESP8266",
170 |         "description": "ESP8266"
171 |     },
172 |     {
173 |         "id": "0x7f83e793",
174 |         "short_name": "KL32L2",
175 |         "description": "NXP KL32L2x"
176 |     },
177 |     {
178 |         "id": "0x8fb060fe",
179 |         "short_name": "STM32F407VG",
180 |         "description": "ST STM32F407VG"
181 |     },
182 |     {
183 |         "id": "0x9fffd543",
184 |         "short_name": "RTL8710A",
185 |         "description": "Realtek Ameba1 RTL8710A"
186 |     },
187 |     {
188 |         "id": "0xada52840",
189 |         "short_name": "NRF52840",
190 |         "description": "Nordic NRF52840"
191 |     },
192 |     {
193 |         "id": "0x820d9a5f",
194 |         "short_name": "NRF52820",
195 |         "description": "Nordic NRF52820_xxAA"
196 |     },
197 |     {
198 |         "id": "0xbfdd4eee",
199 |         "short_name": "ESP32S2",
200 |         "description": "ESP32-S2"
201 |     },
202 |     {
203 |         "id": "0xc47e5767",
204 |         "short_name": "ESP32S3",
205 |         "description": "ESP32-S3"
206 |     },
207 |     {
208 |         "id": "0xd42ba06c",
209 |         "short_name": "ESP32C3",
210 |         "description": "ESP32-C3"
211 |     },
212 |     {
213 |         "id": "0x2b88d29c",
214 |         "short_name": "ESP32C2",
215 |         "description": "ESP32-C2"
216 |     },
217 |     {
218 |         "id": "0x332726f6",
219 |         "short_name": "ESP32H2",
220 |         "description": "ESP32-H2"
221 |     },
222 |     {
223 |         "id": "0x540ddf62",
224 |         "short_name": "ESP32C6",
225 |         "description": "ESP32-C6"
226 |     },
227 |     {
228 |         "id": "0x3d308e94",
229 |         "short_name": "ESP32P4",
230 |         "description": "ESP32-P4"
231 |     },
232 |     {
233 |         "id": "0xf71c0343",
234 |         "short_name": "ESP32C5",
235 |         "description": "ESP32-C5"
236 |     },
237 |     {
238 |         "id": "0x77d850c4",
239 |         "short_name": "ESP32C61",
240 |         "description": "ESP32-C61"
241 |     },
242 |     {
243 |         "id": "0xb6dd00af",
244 |         "short_name": "ESP32H21",
245 |         "description": "ESP32-H21"
246 |     },
247 |     {
248 |         "id": "0x9e0baa8a",
249 |         "short_name": "ESP32H4",
250 |         "description": "ESP32-H4"
251 |     },
252 |     {
253 |         "id": "0xde1270b7",
254 |         "short_name": "BL602",
255 |         "description": "Boufallo 602"
256 |     },
257 |     {
258 |         "id": "0xe08f7564",
259 |         "short_name": "RTL8720C",
260 |         "description": "Realtek AmebaZ2 RTL8720C"
261 |     },
262 |     {
263 |         "id": "0xe48bff56",
264 |         "short_name": "RP2040",
265 |         "description": "Raspberry Pi RP2040"
266 |     },
267 |     {
268 |         "id": "0xe48bff57",
269 |         "short_name": "RP2XXX_ABSOLUTE",
270 |         "description": "Raspberry Pi Microcontrollers: Absolute (unpartitioned) download"
271 |     },
272 |     {
273 |         "id": "0xe48bff58",
274 |         "short_name": "RP2XXX_DATA",
275 |         "description": "Raspberry Pi Microcontrollers: Data partition download"
276 |     },
277 |     {
278 |         "id": "0xe48bff59",
279 |         "short_name": "RP2350_ARM_S",
280 |         "description": "Raspberry Pi RP2350, Secure Arm image"
281 |     },
282 |     {
283 |         "id": "0xe48bff5a",
284 |         "short_name": "RP2350_RISCV",
285 |         "description": "Raspberry Pi RP2350, RISC-V image"
286 |     },
287 |     {
288 |         "id": "0xe48bff5b",
289 |         "short_name": "RP2350_ARM_NS",
290 |         "description": "Raspberry Pi RP2350, Non-secure Arm image"
291 |     },
292 |     {
293 |         "id": "0x00ff6919",
294 |         "short_name": "STM32L4",
295 |         "description": "ST STM32L4xx"
296 |     },
297 |     {
298 |         "id": "0x9af03e33",
299 |         "short_name": "GD32VF103",
300 |         "description": "GigaDevice GD32VF103"
301 |     },
302 |     {
303 |         "id": "0x4f6ace52",
304 |         "short_name": "CSK4",
305 |         "description": "LISTENAI CSK300x/400x"
306 |     },
307 |     {
308 |         "id": "0x6e7348a8",
309 |         "short_name": "CSK6",
310 |         "description": "LISTENAI CSK60xx"
311 |     },
312 |     {
313 |         "id": "0x11de784a",
314 |         "short_name": "M0SENSE",
315 |         "description": "M0SENSE BL702"
316 |     },
317 |     {
318 |         "id": "0x4b684d71",
319 |         "short_name": "MaixPlay-U4",
320 |         "description": "Sipeed MaixPlay-U4(BL618)"
321 |     },
322 |     {
323 |         "id": "0x9517422f",
324 |         "short_name": "RZA1LU",
325 |         "description": "Renesas RZ/A1LU (R7S7210xx)"
326 |     },
327 |     {
328 |         "id": "0x2dc309c5",
329 |         "short_name": "STM32F411xE",
330 |         "description": "ST STM32F411xE"
331 |     },
332 |     {
333 |         "id": "0x06d1097b",
334 |         "short_name": "STM32F411xC",
335 |         "description": "ST STM32F411xC"
336 |     },
337 |     {
338 |         "id": "0x72721d4e",
339 |         "short_name": "NRF52832xxAA",
340 |         "description": "Nordic NRF52832xxAA"
341 |     },
342 |     {
343 |         "id": "0x6f752678",
344 |         "short_name": "NRF52832xxAB",
345 |         "description": "Nordic NRF52832xxAB"
346 |     },
347 |     {
348 |         "id": "0xa0c97b8e",
349 |         "short_name": "AT32F415",
350 |         "description": "ArteryTek AT32F415"
351 |     },
352 |     {
353 |         "id": "0x699b62ec",
354 |         "short_name": "CH32V",
355 |         "description": "WCH CH32V2xx and CH32V3xx"
356 |     },
357 |     {
358 |         "id": "0x7be8976d",
359 |         "short_name": "RA4M1",
360 |         "description": "Renesas RA4M1"
361 |     },
362 |     {
363 |         "id": "0x7410520a",
364 |         "short_name": "MAX32690",
365 |         "description": "Analog Devices MAX32690"
366 |     },
367 |     {
368 |         "id": "0xd63f8632",
369 |         "short_name": "MAX32650",
370 |         "description": "Analog Devices MAX32650/1/2"
371 |     },
372 |     {
373 |         "id": "0xf0c30d71",
374 |         "short_name": "MAX32666",
375 |         "description": "Analog Devices MAX32665/6"
376 |     },
377 |     {
378 |         "id": "0x91d3fd18",
379 |         "short_name": "MAX78002",
380 |         "description": "Analog Devices MAX78002"
381 |     },
382 |     {
383 |         "id": "0x7d7a66ef",
384 |         "short_name": "PY32F071-UVK5-V3",
385 |         "description": "Quansheng UV-K5 V3 amateur radio based on Puya Semiconductor PY32F071"
386 |     }
387 | ]
388 | 


--------------------------------------------------------------------------------
/uf2tool/tool.c:
--------------------------------------------------------------------------------
  1 | #ifdef WIN32
  2 | #include <windows.h>
  3 | #endif
  4 | #include <stdio.h>
  5 | #include <stdlib.h>
  6 | #include <string.h>
  7 | #include <unistd.h>
  8 | #include <sys/time.h>
  9 | #include <stdbool.h>
 10 | #include <pthread.h>
 11 | #include "hidapi.h"
 12 | #include "uf2hid.h"
 13 | 
 14 | #define EP_SIZE 64
 15 | 
 16 | typedef struct {
 17 |     hid_device *dev;
 18 |     uint16_t size;
 19 |     uint8_t serial;
 20 |     uint16_t seqNo;
 21 |     uint16_t pageSize;
 22 |     uint32_t flashSize;
 23 |     uint32_t msgSize;
 24 |     union {
 25 |         uint8_t buf[64 * 1024];
 26 |         HF2_Response resp;
 27 |     };
 28 | } HID_Dev;
 29 | 
 30 | uint64_t millis() {
 31 |     struct timeval tv;
 32 |     gettimeofday(&tv, 0);
 33 |     return tv.tv_sec * 1000 + tv.tv_usec / 1000;
 34 | }
 35 | 
 36 | void fatal(const char *msg) {
 37 |     fprintf(stderr, "Fatal error: %s\n", msg);
 38 |     exit(1);
 39 | }
 40 | 
 41 | void write16(uint8_t *ptr, uint16_t v) {
 42 |     ptr[0] = v;
 43 |     ptr[1] = v >> 8;
 44 | }
 45 | 
 46 | void write32(uint8_t *ptr, uint32_t v) {
 47 |     ptr[0] = v;
 48 |     ptr[1] = v >> 8;
 49 |     ptr[2] = v >> 16;
 50 |     ptr[3] = v >> 24;
 51 | }
 52 | 
 53 | uint32_t read32(uint8_t *ptr) { return ptr[0] | (ptr[1] << 8) | (ptr[2] << 16) | (ptr[3] << 24); }
 54 | 
 55 | uint32_t read16(uint8_t *ptr) { return ptr[0] | (ptr[1] << 8); }
 56 | 
 57 | int recv_hid(HID_Dev *pkt, int timeout) {
 58 |     uint8_t buf0[EP_SIZE + 1];
 59 |     uint8_t *buf;
 60 | 
 61 |     pkt->size = 0;
 62 |     memset(pkt->buf, 0, sizeof(pkt->buf));
 63 | 
 64 |     for (;;) {
 65 |         int sz = hid_read_timeout(pkt->dev, buf0, sizeof(buf0), timeout);
 66 |         if (sz <= 0) {
 67 |             if (timeout < 0)
 68 |                 fatal("read error");
 69 |             return 0;
 70 |         }
 71 |         buf = buf0;
 72 |         if (!*buf)
 73 |             buf++; // skip report number if passed
 74 | 
 75 |         uint8_t tag = buf[0];
 76 |         if (pkt->size && (tag & HF2_FLAG_SERIAL_OUT))
 77 |             fatal("invalid serial transfer");
 78 |         uint32_t newsize = pkt->size + (tag & HF2_SIZE_MASK);
 79 |         if (newsize > sizeof(pkt->buf))
 80 |             fatal("too large packet");
 81 |         memcpy(pkt->buf + pkt->size, buf + 1, tag & HF2_SIZE_MASK);
 82 |         pkt->size = newsize;
 83 | 
 84 |         tag &= HF2_FLAG_MASK;
 85 |         if (tag != HF2_FLAG_CMDPKT_BODY) {
 86 |             pkt->serial = //
 87 |                 tag == HF2_FLAG_SERIAL_OUT ? 1 : tag == HF2_FLAG_SERIAL_ERR ? 2 : 0;
 88 |             return 1;
 89 |         }
 90 | 
 91 |         timeout = -1; // next read is blocking
 92 |     }
 93 | }
 94 | 
 95 | void send_hid(hid_device *dev, const void *data, int size) {
 96 |     uint8_t buf[EP_SIZE + 1] = {0};
 97 |     const uint8_t *ptr = data;
 98 | 
 99 |     for (;;) {
100 |         int s;
101 |         if (size <= EP_SIZE - 1) {
102 |             s = size;
103 |             buf[1] = HF2_FLAG_CMDPKT_LAST | size;
104 |         } else {
105 |             s = EP_SIZE - 1;
106 |             buf[1] = HF2_FLAG_CMDPKT_BODY | (EP_SIZE - 1);
107 |         }
108 |         memcpy(buf + 2, ptr, s);
109 |         int sz = hid_write(dev, buf, EP_SIZE + 1);
110 |         if (sz != EP_SIZE + 1)
111 |             fatal("write error");
112 |         ptr += s;
113 |         size -= s;
114 |         if (!size)
115 |             break;
116 |     }
117 | }
118 | 
119 | void talk_hid(HID_Dev *pkt, int cmd, const void *data, uint32_t len) {
120 |     if (len >= sizeof(pkt->buf) - 8)
121 |         fatal("buffer overflow");
122 |     if (data)
123 |         memcpy(pkt->buf + 8, data, len);
124 |     write32(pkt->buf, cmd);
125 |     write16(pkt->buf + 4, ++pkt->seqNo);
126 |     write16(pkt->buf + 6, 0);
127 |     send_hid(pkt->dev, pkt->buf, 8 + len);
128 | 
129 |     if (cmd == HF2_CMD_RESET_INTO_APP)
130 |         return; // no response expected
131 | 
132 |     recv_hid(pkt, -1);
133 |     if (read16(pkt->buf) != pkt->seqNo)
134 |         fatal("invalid sequence number");
135 |     if (read16(pkt->buf + 2))
136 |         fatal("invalid status");
137 | }
138 | 
139 | uint8_t flashbuf[2 * 1024 * 1024];
140 | 
141 | unsigned short add_crc(char ptr, unsigned short crc) {
142 |     unsigned short cmpt;
143 |     crc = crc ^ (int)ptr << 8;
144 |     for (cmpt = 0; cmpt < 8; cmpt++) {
145 |         if (crc & 0x8000)
146 |             crc = crc << 1 ^ 0x1021;
147 |         else
148 |             crc = crc << 1;
149 |     }
150 |     return (crc & 0xFFFF);
151 | }
152 | 
153 | void verify(HID_Dev *cmd, uint8_t *buf, int size, int offset) {
154 |     int maxSize = (cmd->pageSize / 2 - 12) * cmd->pageSize;
155 |     while (size > maxSize) {
156 |         verify(cmd, buf, maxSize, offset);
157 |         buf += maxSize;
158 |         offset += maxSize;
159 |         size -= maxSize;
160 |     }
161 |     int numpages = size / cmd->pageSize;
162 |     write32(cmd->buf + 8, offset);
163 |     write32(cmd->buf + 12, numpages);
164 |     talk_hid(cmd, HF2_CMD_CHKSUM_PAGES, 0, 8);
165 |     for (int i = 0; i < numpages; ++i) {
166 |         int sum = read16(cmd->buf + 4 + i * 2);
167 |         uint16_t crc = 0;
168 |         for (int j = 0; j < cmd->pageSize; ++j) {
169 |             crc = add_crc(buf[j], crc);
170 |         }
171 |         if (sum != crc)
172 |             fatal("verification failed");
173 |         buf += cmd->pageSize;
174 |     }
175 | }
176 | 
177 | void *forward_stdin(void *cmd0) {
178 |     uint8_t buf[EP_SIZE + 1];
179 |     HID_Dev *cmd = cmd0;
180 |     for (;;) {
181 |         memset(buf, 0, sizeof(buf));
182 |         int sz = read(0, buf + 2, EP_SIZE - 1);
183 |         if (sz > 0) {
184 |             buf[1] = HF2_FLAG_SERIAL_OUT | sz;
185 |             hid_write(cmd->dev, buf, EP_SIZE + 1);
186 |         }
187 |         if (sz == 0)
188 |             break;
189 |     }
190 |     return NULL;
191 | }
192 | 
193 | void serial(HID_Dev *cmd) {
194 |     pthread_t stdinFwd;
195 |     pthread_create(&stdinFwd, NULL, forward_stdin, cmd);
196 |     for (;;) {
197 |         if (recv_hid(cmd, -1)) {
198 |             if (cmd->serial)
199 |                 write(cmd->serial, cmd->buf, cmd->size);
200 |         }
201 |     }
202 | }
203 | 
204 | int main(int argc, char *argv[]) {
205 |     int res;
206 |     HID_Dev cmd = {0};
207 | 
208 |     if (argc != 2) {
209 |         printf("usage: %s COMMAND [ARGUMENTS...]\n", argv[0]);
210 |         printf("Commands include:\n");
211 |         printf("   serial           - run 'serial' port forwarding\n");
212 |         printf("   list             - list devices\n");
213 |         printf("   dmesg            - dump internal runtime logs from the device\n");
214 |         printf("   info             - dump information about the device\n");
215 |         printf("   FILE             - write specified BIN or UF2 file\n");
216 |         printf("   random           - write randomly generated bin file\n");
217 |         return 1;
218 |     }
219 | 
220 |     const char *filename = argv[1];
221 | 
222 |     // Initialize the hidapi library
223 |     res = hid_init();
224 | 
225 |     bool listMode = strcmp(filename, "list") == 0;
226 | 
227 |     struct hid_device_info *devs = hid_enumerate(0, 0);
228 |     for (struct hid_device_info *p = devs; p; p = p->next) {
229 |         int isOK = (p->release_number & 0xff00) == 0x4200;
230 |         const char *path = strstr(p->path, "@1400");
231 |         if (!path)
232 |             path = p->path;
233 |         if (listMode) {
234 |             // exclude Apple devices
235 |             if (p->vendor_id != 0x05ac)
236 |                 printf("%s: %04x:%04x %04x %s\n", isOK ? "HF2" : "...", p->vendor_id, p->product_id,
237 |                        p->release_number, path);
238 |         }
239 |         if (isOK) {
240 |             cmd.dev = hid_open_path(p->path);
241 |         }
242 |     }
243 |     hid_free_enumeration(devs);
244 |     if (listMode)
245 |         return 0;
246 |     if (!cmd.dev) {
247 |         printf("no devices\n");
248 |         return 1;
249 |     }
250 | 
251 |     if (strcmp(filename, "serial") == 0) {
252 |         serial(&cmd);
253 |         return 0;
254 |     }
255 | 
256 |     if (strcmp(filename, "dmesg") == 0) {
257 |         talk_hid(&cmd, HF2_CMD_DMESG, 0, 0);
258 |         printf("%s\n", cmd.buf + 4);
259 |         return 0;
260 |     }
261 | 
262 |     talk_hid(&cmd, HF2_CMD_INFO, 0, 0);
263 |     printf("INFO: %s\n", cmd.buf + 4);
264 | 
265 |     talk_hid(&cmd, HF2_CMD_START_FLASH, 0, 0);
266 | 
267 |     talk_hid(&cmd, HF2_CMD_BININFO, 0, 0);
268 |     if (cmd.buf[4] != HF2_MODE_BOOTLOADER)
269 |         fatal("not bootloader");
270 | 
271 |     cmd.pageSize = read32(cmd.buf + 8);
272 |     cmd.flashSize = read32(cmd.buf + 12) * cmd.pageSize;
273 |     cmd.msgSize = read32(cmd.buf + 16);
274 |     printf("page size: %d, total: %dkB\n", cmd.pageSize, cmd.flashSize / 1024);
275 | 
276 |     if (strcmp(filename, "info") == 0) {
277 |         return 0;
278 |     }
279 | 
280 |     int i;
281 |     size_t filesize;
282 |     int isUF2 = 0;
283 | 
284 |     if (strcmp(filename, "random") == 0) {
285 |         srand(millis());
286 |         filesize = 230 * 1024;
287 |         for (i = 0; i < filesize; ++i)
288 |             flashbuf[i] = rand();
289 |     } else {
290 |         FILE *f = fopen(filename, "rb");
291 |         if (!f) {
292 |             fatal("cannot open file");
293 |         }
294 |         int len = 1;
295 |         filesize = 0;
296 |         while (len) {
297 |             len = fread(flashbuf + filesize, 1, sizeof(flashbuf) - filesize, f);
298 |             filesize += len;
299 |         }
300 |         if (strncmp((const char *)flashbuf, "UF2\nWQ]\x9E", 8) == 0) {
301 |             printf("detected UF2 file\n");
302 |             if (cmd.pageSize != 256)
303 |                 fatal("wrong page size");
304 |             isUF2 = 1;
305 |         } else {
306 |             filesize = (filesize + (cmd.pageSize - 1)) / cmd.pageSize * cmd.pageSize;
307 |         }
308 |         printf("read %ld bytes from %s\n", filesize, filename);
309 |         fclose(f);
310 |     }
311 | 
312 |     uint64_t start = millis();
313 |     uint32_t addr = 0x2000;
314 |     uint32_t blockSize = cmd.pageSize;
315 | 
316 |     if (isUF2)
317 |         blockSize = 512;
318 | 
319 |     for (i = 0; i < filesize; i += blockSize) {
320 |         if (isUF2) {
321 |             addr = read32(flashbuf + i + 12);
322 |             memcpy(cmd.buf + 12, flashbuf + i + 32, cmd.pageSize);
323 |         } else {
324 |             memcpy(cmd.buf + 12, flashbuf + i, cmd.pageSize);
325 |         }
326 |         write32(cmd.buf + 8, addr);
327 |         talk_hid(&cmd, HF2_CMD_WRITE_FLASH_PAGE, 0, cmd.pageSize + 4);
328 |         addr += cmd.pageSize;
329 |     }
330 | 
331 |     printf("time: %d\n", (int)(millis() - start));
332 |     start = millis();
333 | 
334 | #if 0
335 |     for (i = 0; i < filesize; i += cmd.pageSize) {
336 |         write32(cmd.buf + 8, i + 0x2000);
337 |         write32(cmd.buf + 12, cmd.pageSize / 4);
338 |         talk_hid(&cmd, HF2_CMD_MEM_READ_WORDS, 0, 8);
339 |         if (memcmp(cmd.buf + 4, flashbuf + i, cmd.pageSize)) {
340 |             printf("%d,%d,%d != %d?\n", cmd.buf[8], cmd.buf[9], cmd.buf[10], flashbuf[i]);
341 |             fatal("verification failed");
342 |         }
343 |     }
344 | #else
345 |     if (!isUF2)
346 |         verify(&cmd, flashbuf, filesize, 0x2000);
347 | #endif
348 | 
349 |     printf("verify time: %d\n", (int)(millis() - start));
350 | 
351 |     talk_hid(&cmd, HF2_CMD_RESET_INTO_APP, 0, 0);
352 | 
353 |     printf("device reset.\n");
354 | 
355 |     // Finalize the hidapi library
356 |     res = hid_exit();
357 | 
358 |     return 0;
359 | }
360 | 


--------------------------------------------------------------------------------
/utils/uf2conv.py:
--------------------------------------------------------------------------------
  1 | #!/usr/bin/env python3
  2 | import sys
  3 | import struct
  4 | import subprocess
  5 | import re
  6 | import os
  7 | import os.path
  8 | import argparse
  9 | import json
 10 | from time import sleep
 11 | 
 12 | 
 13 | UF2_MAGIC_START0 = 0x0A324655 # "UF2\n"
 14 | UF2_MAGIC_START1 = 0x9E5D5157 # Randomly selected
 15 | UF2_MAGIC_END    = 0x0AB16F30 # Ditto
 16 | 
 17 | INFO_FILE = "/INFO_UF2.TXT"
 18 | 
 19 | appstartaddr = 0x2000
 20 | familyid = 0x0
 21 | 
 22 | 
 23 | def is_uf2(buf):
 24 |     w = struct.unpack("<II", buf[0:8])
 25 |     return w[0] == UF2_MAGIC_START0 and w[1] == UF2_MAGIC_START1
 26 | 
 27 | def is_hex(buf):
 28 |     try:
 29 |         w = buf[0:30].decode("utf-8")
 30 |     except UnicodeDecodeError:
 31 |         return False
 32 |     if w[0] == ':' and re.match(rb"^[:0-9a-fA-F\r\n]+$", buf):
 33 |         return True
 34 |     return False
 35 | 
 36 | def convert_from_uf2(buf):
 37 |     global appstartaddr
 38 |     global familyid
 39 |     numblocks = len(buf) // 512
 40 |     curraddr = None
 41 |     currfamilyid = None
 42 |     families_found = {}
 43 |     prev_flag = None
 44 |     all_flags_same = True
 45 |     outp = []
 46 |     for blockno in range(numblocks):
 47 |         ptr = blockno * 512
 48 |         block = buf[ptr:ptr + 512]
 49 |         hd = struct.unpack(b"<IIIIIIII", block[0:32])
 50 |         if hd[0] != UF2_MAGIC_START0 or hd[1] != UF2_MAGIC_START1:
 51 |             print("Skipping block at " + ptr + "; bad magic")
 52 |             continue
 53 |         if hd[2] & 1:
 54 |             # NO-flash flag set; skip block
 55 |             continue
 56 |         datalen = hd[4]
 57 |         if datalen > 476:
 58 |             assert False, "Invalid UF2 data size at " + ptr
 59 |         newaddr = hd[3]
 60 |         if (hd[2] & 0x2000) and (currfamilyid == None):
 61 |             currfamilyid = hd[7]
 62 |         if curraddr == None or ((hd[2] & 0x2000) and hd[7] != currfamilyid):
 63 |             currfamilyid = hd[7]
 64 |             curraddr = newaddr
 65 |             if familyid == 0x0 or familyid == hd[7]:
 66 |                 appstartaddr = newaddr
 67 |         padding = newaddr - curraddr
 68 |         if padding < 0:
 69 |             assert False, "Block out of order at " + ptr
 70 |         if padding > 10*1024*1024:
 71 |             assert False, "More than 10M of padding needed at " + ptr
 72 |         if padding % 4 != 0:
 73 |             assert False, "Non-word padding size at " + ptr
 74 |         while padding > 0:
 75 |             padding -= 4
 76 |             outp.append(b"\x00\x00\x00\x00")
 77 |         if familyid == 0x0 or ((hd[2] & 0x2000) and familyid == hd[7]):
 78 |             outp.append(block[32 : 32 + datalen])
 79 |         curraddr = newaddr + datalen
 80 |         if hd[2] & 0x2000:
 81 |             if hd[7] in families_found.keys():
 82 |                 if families_found[hd[7]] > newaddr:
 83 |                     families_found[hd[7]] = newaddr
 84 |             else:
 85 |                 families_found[hd[7]] = newaddr
 86 |         if prev_flag == None:
 87 |             prev_flag = hd[2]
 88 |         if prev_flag != hd[2]:
 89 |             all_flags_same = False
 90 |         if blockno == (numblocks - 1):
 91 |             print("--- UF2 File Header Info ---")
 92 |             families = load_families()
 93 |             for family_hex in families_found.keys():
 94 |                 family_short_name = ""
 95 |                 for name, value in families.items():
 96 |                     if value == family_hex:
 97 |                         family_short_name = name
 98 |                 print("Family ID is {:s}, hex value is 0x{:08x}".format(family_short_name,family_hex))
 99 |                 print("Target Address is 0x{:08x}".format(families_found[family_hex]))
100 |             if all_flags_same:
101 |                 print("All block flag values consistent, 0x{:04x}".format(hd[2]))
102 |             else:
103 |                 print("Flags were not all the same")
104 |             print("----------------------------")
105 |             if len(families_found) > 1 and familyid == 0x0:
106 |                 outp = []
107 |                 appstartaddr = 0x0
108 |     return b"".join(outp)
109 | 
110 | def convert_to_carray(file_content):
111 |     outp = "const unsigned long bindata_len = %d;\n" % len(file_content)
112 |     outp += "const unsigned char bindata[] __attribute__((aligned(16))) = {"
113 |     for i in range(len(file_content)):
114 |         if i % 16 == 0:
115 |             outp += "\n"
116 |         outp += "0x%02x, " % file_content[i]
117 |     outp += "\n};\n"
118 |     return bytes(outp, "utf-8")
119 | 
120 | def convert_to_uf2(file_content):
121 |     global familyid
122 |     datapadding = b""
123 |     while len(datapadding) < 512 - 256 - 32 - 4:
124 |         datapadding += b"\x00\x00\x00\x00"
125 |     numblocks = (len(file_content) + 255) // 256
126 |     outp = []
127 |     for blockno in range(numblocks):
128 |         ptr = 256 * blockno
129 |         chunk = file_content[ptr:ptr + 256]
130 |         flags = 0x0
131 |         if familyid:
132 |             flags |= 0x2000
133 |         hd = struct.pack(b"<IIIIIIII",
134 |             UF2_MAGIC_START0, UF2_MAGIC_START1,
135 |             flags, ptr + appstartaddr, 256, blockno, numblocks, familyid)
136 |         while len(chunk) < 256:
137 |             chunk += b"\x00"
138 |         block = hd + chunk + datapadding + struct.pack(b"<I", UF2_MAGIC_END)
139 |         assert len(block) == 512
140 |         outp.append(block)
141 |     return b"".join(outp)
142 | 
143 | class Block:
144 |     def __init__(self, addr, default_data=0xFF):
145 |         self.addr = addr
146 |         self.bytes = bytearray([default_data] * 256)
147 | 
148 |     def encode(self, blockno, numblocks):
149 |         global familyid
150 |         flags = 0x0
151 |         if familyid:
152 |             flags |= 0x2000
153 |         hd = struct.pack("<IIIIIIII",
154 |             UF2_MAGIC_START0, UF2_MAGIC_START1,
155 |             flags, self.addr, 256, blockno, numblocks, familyid)
156 |         hd += self.bytes[0:256]
157 |         while len(hd) < 512 - 4:
158 |             hd += b"\x00"
159 |         hd += struct.pack("<I", UF2_MAGIC_END)
160 |         return hd
161 | 
162 | def convert_from_hex_to_uf2(buf):
163 |     global appstartaddr
164 |     appstartaddr = None
165 |     upper = 0
166 |     currblock = None
167 |     blocks = []
168 |     for line in buf.split('\n'):
169 |         if line[0] != ":":
170 |             continue
171 |         i = 1
172 |         rec = []
173 |         while i < len(line) - 1:
174 |             rec.append(int(line[i:i+2], 16))
175 |             i += 2
176 |         tp = rec[3]
177 |         if tp == 4:
178 |             upper = ((rec[4] << 8) | rec[5]) << 16
179 |         elif tp == 2:
180 |             upper = ((rec[4] << 8) | rec[5]) << 4
181 |         elif tp == 1:
182 |             break
183 |         elif tp == 0:
184 |             addr = upper + ((rec[1] << 8) | rec[2])
185 |             if appstartaddr == None:
186 |                 appstartaddr = addr
187 |             i = 4
188 |             while i < len(rec) - 1:
189 |                 if not currblock or currblock.addr & ~0xff != addr & ~0xff:
190 |                     currblock = Block(addr & ~0xff)
191 |                     blocks.append(currblock)
192 |                 currblock.bytes[addr & 0xff] = rec[i]
193 |                 addr += 1
194 |                 i += 1
195 |     numblocks = len(blocks)
196 |     resfile = b""
197 |     for i in range(0, numblocks):
198 |         resfile += blocks[i].encode(i, numblocks)
199 |     return resfile
200 | 
201 | def to_str(b):
202 |     return b.decode("utf-8")
203 | 
204 | def get_drives():
205 |     drives = []
206 |     if sys.platform == "win32":
207 |         r = subprocess.check_output([
208 |             "powershell",
209 |             "-Command",
210 |             '(Get-WmiObject Win32_LogicalDisk -Filter "FileSystem=\'FAT\'").DeviceID'
211 |             ])
212 |         drives = [drive.strip() for drive in to_str(r).splitlines()]
213 |     else:
214 |         searchpaths = ["/mnt", "/media"]
215 |         if sys.platform == "darwin":
216 |             searchpaths = ["/Volumes"]
217 |         elif sys.platform == "linux":
218 |             searchpaths += ["/media/" + os.environ["USER"], "/run/media/" + os.environ["USER"]]
219 |             if "SUDO_USER" in os.environ.keys():
220 |                 searchpaths += ["/media/" + os.environ["SUDO_USER"]]
221 |                 searchpaths += ["/run/media/" + os.environ["SUDO_USER"]]
222 | 
223 |         for rootpath in searchpaths:
224 |             if os.path.isdir(rootpath):
225 |                 for d in os.listdir(rootpath):
226 |                     if os.path.isdir(os.path.join(rootpath, d)):
227 |                         drives.append(os.path.join(rootpath, d))
228 | 
229 | 
230 |     def has_info(d):
231 |         try:
232 |             return os.path.isfile(d + INFO_FILE)
233 |         except:
234 |             return False
235 | 
236 |     return list(filter(has_info, drives))
237 | 
238 | 
239 | def board_id(path):
240 |     with open(path + INFO_FILE, mode='r') as file:
241 |         file_content = file.read()
242 |     return re.search(r"Board-ID: ([^\r\n]*)", file_content).group(1)
243 | 
244 | 
245 | def list_drives():
246 |     for d in get_drives():
247 |         print(d, board_id(d))
248 | 
249 | 
250 | def write_file(name, buf):
251 |     with open(name, "wb") as f:
252 |         f.write(buf)
253 |     print("Wrote %d bytes to %s" % (len(buf), name))
254 | 
255 | 
256 | def load_families():
257 |     # The expectation is that the `uf2families.json` file is in the same
258 |     # directory as this script. Make a path that works using `__file__`
259 |     # which contains the full path to this script.
260 |     filename = "uf2families.json"
261 |     pathname = os.path.join(os.path.dirname(os.path.abspath(__file__)), filename)
262 |     with open(pathname) as f:
263 |         raw_families = json.load(f)
264 | 
265 |     families = {}
266 |     for family in raw_families:
267 |         families[family["short_name"]] = int(family["id"], 0)
268 | 
269 |     return families
270 | 
271 | 
272 | def main():
273 |     global appstartaddr, familyid
274 |     def error(msg):
275 |         print(msg, file=sys.stderr)
276 |         sys.exit(1)
277 |     parser = argparse.ArgumentParser(description='Convert to UF2 or flash directly.')
278 |     parser.add_argument('input', metavar='INPUT', type=str, nargs='?',
279 |                         help='input file (HEX, BIN or UF2)')
280 |     parser.add_argument('-b', '--base', dest='base', type=str,
281 |                         default="0x2000",
282 |                         help='set base address of application for BIN format (default: 0x2000)')
283 |     parser.add_argument('-f', '--family', dest='family', type=str,
284 |                         default="0x0",
285 |                         help='specify familyID - number or name (default: 0x0)')
286 |     parser.add_argument('-o', '--output', metavar="FILE", dest='output', type=str,
287 |                         help='write output to named file; defaults to "flash.uf2" or "flash.bin" where sensible')
288 |     parser.add_argument('-d', '--device', dest="device_path",
289 |                         help='select a device path to flash')
290 |     parser.add_argument('-l', '--list', action='store_true',
291 |                         help='list connected devices')
292 |     parser.add_argument('-c', '--convert', action='store_true',
293 |                         help='do not flash, just convert')
294 |     parser.add_argument('-D', '--deploy', action='store_true',
295 |                         help='just flash, do not convert')
296 |     parser.add_argument('-w', '--wait', action='store_true',
297 |                         help='wait for device to flash')
298 |     parser.add_argument('-C', '--carray', action='store_true',
299 |                         help='convert binary file to a C array, not UF2')
300 |     parser.add_argument('-i', '--info', action='store_true',
301 |                         help='display header information from UF2, do not convert')
302 |     args = parser.parse_args()
303 |     appstartaddr = int(args.base, 0)
304 | 
305 |     families = load_families()
306 | 
307 |     if args.family.upper() in families:
308 |         familyid = families[args.family.upper()]
309 |     else:
310 |         try:
311 |             familyid = int(args.family, 0)
312 |         except ValueError:
313 |             error("Family ID needs to be a number or one of: " + ", ".join(families.keys()))
314 | 
315 |     if args.list:
316 |         list_drives()
317 |     else:
318 |         if not args.input:
319 |             error("Need input file")
320 |         with open(args.input, mode='rb') as f:
321 |             inpbuf = f.read()
322 |         from_uf2 = is_uf2(inpbuf)
323 |         ext = "uf2"
324 |         if args.deploy:
325 |             outbuf = inpbuf
326 |         elif from_uf2 and not args.info:
327 |             outbuf = convert_from_uf2(inpbuf)
328 |             ext = "bin"
329 |         elif from_uf2 and args.info:
330 |             outbuf = ""
331 |             convert_from_uf2(inpbuf)
332 |         elif is_hex(inpbuf):
333 |             outbuf = convert_from_hex_to_uf2(inpbuf.decode("utf-8"))
334 |         elif args.carray:
335 |             outbuf = convert_to_carray(inpbuf)
336 |             ext = "h"
337 |         else:
338 |             outbuf = convert_to_uf2(inpbuf)
339 |         if not args.deploy and not args.info:
340 |             print("Converted to %s, output size: %d, start address: 0x%x" %
341 |                   (ext, len(outbuf), appstartaddr))
342 |         if args.convert or ext != "uf2":
343 |             if args.output == None:
344 |                 args.output = "flash." + ext
345 |         if args.output:
346 |             write_file(args.output, outbuf)
347 |         if ext == "uf2" and not args.convert and not args.info:
348 |             drives = get_drives()
349 |             if len(drives) == 0:
350 |                 if args.wait:
351 |                     print("Waiting for drive to deploy...")
352 |                     while len(drives) == 0:
353 |                         sleep(0.1)
354 |                         drives = get_drives()
355 |                 elif not args.output:
356 |                     error("No drive to deploy.")
357 |             for d in drives:
358 |                 print("Flashing %s (%s)" % (d, board_id(d)))
359 |                 write_file(d + "/NEW.UF2", outbuf)
360 | 
361 | 
362 | if __name__ == "__main__":
363 |     main()
364 | 


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
  1 | # USB Flashing Format (UF2)
  2 | 
  3 | UF2 is a file format, developed by Microsoft for [PXT](https://github.com/Microsoft/pxt) 
  4 | (also known as [Microsoft MakeCode](https://makecode.com)), that is particularly suitable for 
  5 | flashing microcontrollers over MSC (Mass Storage Class; aka removable flash drive).
  6 | 
  7 | For a more friendly explanation, check out [this blog post](https://makecode.com/blog/one-chip-to-flash-them-all).
  8 | Also, take a look at the list of [implementations](#implementations) at the bottom of this document.
  9 | 
 10 | ## Overview
 11 | 
 12 | The UF2 file consists of 512 byte blocks, each of which is self-contained and independent of others. 
 13 | Each 512 byte block consists of (see below for details):
 14 | * magic numbers at the beginning and at the end
 15 | * address where the data should be flashed
 16 | * up to 476 bytes of data
 17 | 
 18 | The data transfers over MSC always arrive in multiples of 512 bytes.
 19 | Together with the FAT file system structure, this means that blocks of the
 20 | UF2 file are always aligned with the MSC writes - the microcontroller 
 21 | never gets a partial file.
 22 | 
 23 | The magic numbers let the microcontroller distinguish an UF2 file block from
 24 | other data (eg., FAT table entry, or various book-keeping files stored by some
 25 | operating systems).  When a UF2 block is recognized, it can be flashed
 26 | immediately (unless flash page size is more than 256 bytes; in that case a buffer
 27 | is needed). The actual handling of file format during writing is very simple
 28 | (~10 lines of C code in simplest version).
 29 | 
 30 | ## File format
 31 | 
 32 | A UF2 file consists of 512 byte blocks. Each block starts with a 32 byte
 33 | header, followed by data, and a final magic number.
 34 | All fields, except for data, are 32 bit unsigned little endian integers.
 35 | 
 36 | | Offset | Size | Value                                             |
 37 | |--------|------|---------------------------------------------------|
 38 | | 0      | 4    | First magic number, `0x0A324655` (`"UF2\n"`)      |
 39 | | 4      | 4    | Second magic number, `0x9E5D5157`                 |
 40 | | 8      | 4    | Flags                                             |
 41 | | 12     | 4    | Address in flash where the data should be written |
 42 | | 16     | 4    | Number of bytes used in data (often 256)          |
 43 | | 20     | 4    | Sequential block number; starts at 0              |
 44 | | 24     | 4    | Total number of blocks in file                    |
 45 | | 28     | 4    | File size or board family ID or zero              |
 46 | | 32     | 476  | Data, padded with zeros                           |
 47 | | 508    | 4    | Final magic number, `0x0AB16F30`                  |
 48 | 
 49 | The following C struct can be used:
 50 | 
 51 | ```C
 52 | struct UF2_Block {
 53 |     // 32 byte header
 54 |     uint32_t magicStart0;
 55 |     uint32_t magicStart1;
 56 |     uint32_t flags;
 57 |     uint32_t targetAddr;
 58 |     uint32_t payloadSize;
 59 |     uint32_t blockNo;
 60 |     uint32_t numBlocks;
 61 |     uint32_t fileSize; // or familyID;
 62 |     uint8_t data[476];
 63 |     uint32_t magicEnd;
 64 | } UF2_Block;
 65 | ```
 66 | 
 67 | ### Flags
 68 | 
 69 | Currently, there are five flags defined:
 70 | 
 71 | * `0x00000001` - **not main flash** - this block should be skipped when writing the
 72 |   device flash; it can be used to store "comments" in the file, typically
 73 |   embedded source code or debug info that does not fit on the device flash
 74 | * `0x00001000` - **file container** - see below
 75 | * `0x00002000` - **familyID present** - when set, the `fileSize/familyID` holds a value
 76 |   identifying the board family (usually corresponds to an MCU)
 77 | * `0x00004000` - **MD5 checksum present** - see below
 78 | * `0x00008000` - **extension tags present** - see below
 79 | 
 80 | ### Family ID
 81 | 
 82 | This field is optional, and should be set only when the corresponding
 83 | flag is set. It is recommended that new bootloaders require the field to
 84 | be set appropriately, and refuse to flash UF2 files without it.
 85 | If you're developing your own bootloader, and your
 86 | board family isn't listed here, pick a new family ID at random. It's good
 87 | to also send a PR here, so your family can be listed.
 88 | 
 89 | If the `familyID` doesn't match, the bootloader should disregard the
 90 | entire block, including `blockNo` and `numBlocks` fields.
 91 | In particular, writing a full UF2 file with non-matching `familyID`
 92 | should not reset the board.
 93 | This also allows for several files with different `familyID` to be
 94 | simply concatenated together, and the whole resulting file to be copied
 95 | to the device with only one actually being written to flash.
 96 | 
 97 | #### Picking numbers at random
 98 | 
 99 | The reason to pick numbers at random is to minimize risk of collisions
100 | in the wild. Do not pick random numbers by banging on keyboard, or by using
101 | `0xdeadf00d`, `0x42424242` etc. A good way is to use the following
102 | shell command: `printf "0x%04x%04x\n" $RANDOM $RANDOM`
103 | Another good way is the link at the bottom of https://microsoft.github.io/uf2/patcher/
104 | This procedure was unfortunately not used for the SAMD51 and NRF52840 below.
105 | 
106 | #### Family list
107 | 
108 | The current master list of family IDs is maintained in a [JSON file](utils/uf2families.json).
109 | 
110 | ### Rationale
111 | 
112 | The magic number at the end is meant to mitigate partial block writes.
113 | 
114 | Second and final magic numbers were randomly selected, except for the last byte
115 | of final magic number, which was forced to be `'\n'` (`0xA`). Together with the
116 | first magic number being `"UF2\n"` this makes it easy to identify UF2 blocks in
117 | a text editor.
118 | 
119 | The header is padded to 32 bytes, as hex editors commonly use 16 or 32 bytes
120 | as line length.  This way, the data payload is aligned to line start.
121 | 
122 | 32 bit integers are used for all fields so that large flash sizes can be
123 | supported in future, as well as for simplicity. Little endian is used, as most
124 | microcontrollers are little endian. 8 bit microcontrollers can choose to just
125 | use the first 16 bits of various header fields.
126 | 
127 | The total number of blocks in the file and the sequential block number make it
128 | easy for the bootloader to detect that all blocks have been transferred. It
129 | requires one bit of memory per block (eg., on SAMD21G18A it's 128 bytes).
130 | Alternatively, the bootloader might ignore that and just implement a reset
131 | after say 1 second break in incoming UF2 blocks.
132 | 
133 | ### Payload sizes
134 | 
135 | The number of data bytes is configurable and depends on the size of
136 | the flash page (that is the smallest size that can be erased) on the
137 | microcontroller.
138 | 
139 | * if the page size is more than `476` bytes, the bootloader should support
140 |   any payload size, as it needs to buffer the entire page in memory anyway
141 | * if the page size is less than `476` bytes, the payload should be a multiple
142 |   of page size, so it can be written without buffering; the target address
143 |   should also be a multiple of page size
144 | 
145 | In any event, payload size and target address should always be 4-byte aligned.
146 | 
147 | Note that payload size of `256` is always correct, and makes it easy to convert
148 | between flash addresses and UF2 file offsets.
149 | 
150 | For example, on Atmel's SAMD21 chips the page size is `256` bytes, and this 
151 | also is the payload size. If the page size was `128` bytes, one could use
152 | payload of `128*3`. Nordic nRF51 has page size of `1024` bytes, and thus 
153 | any payload size should be allowed.
154 | 
155 | ### Embedding sources
156 | 
157 | Some IDEs will embed program sources in the UF2 file. This allows a UF2 files to be
158 | loaded by the IDE and serve as a natural backup and transfer format.
159 | This can be done in two ways:
160 | 
161 | * using the "not main flash" flag
162 | * using normal blocks that are flashed to the device
163 | 
164 | If the bootloader can expose `CURRENT.UF2` file (see below) and there is enough
165 | flash available, than the second option is more desirable, as it allows sharing
166 | programs directly from the board.
167 | 
168 | See https://makecode.com/source-embedding for more info.
169 | 
170 | ### Robustness
171 | 
172 | The file format is designed specifically to deal with the following problems:
173 | 
174 | * operating system (OS) writing blocks in different order than occurs in a file
175 | * OS writing blocks multiple times
176 | * OS writing data that is not UF2 blocks
177 | * OS writing first/final part of a block, possibly for metadata detection or search indexing
178 | 
179 | The only file system assumption we make is that blocks of file are aligned with
180 | blocks on the hard drive. It's likely true of many file systems besides FAT.
181 | 
182 | We also assume that USB MSC device reports its block size to be a multiple of `512`
183 | bytes. In the wild these devices always almost report exactly `512`, and some
184 | operating systems do not support other values.
185 | 
186 | ## Files exposed by bootloaders
187 | 
188 | Bootloaders may expose virtual files in their MSC devices.  These are
189 | standardized here, so that flashing tools can automatically detect the
190 | bootloaders.
191 | 
192 | * `INFO_UF2.TXT` - contains information about the bootloader build and the board on which it is running
193 | * `INDEX.HTM` - redirects to a page that contains an IDE or other information
194 | * `CURRENT.UF2` - the contents of the entire flash of the device, starting at `0x00000000`, with `256` payload size;
195 |   thus, the size of this file will report as twice the size of flash
196 | 
197 | Flashing tools can use the presence of `INFO_UF2.TXT` (in upper or lower case,
198 | as FAT is case-insensitive) file as an indication that a given directory is
199 | actually a connected UF2 board. The other files should not be used for
200 | detection.
201 | 
202 | Typical `INFO_UF2.TXT` file looks like this:
203 | ```
204 | UF2 Bootloader v1.1.3 SFA
205 | Model: Arduino Zero
206 | Board-ID: SAMD21G18A-Zero-v0
207 | ```
208 | 
209 | The `Board-ID` field is machine-readable and consists of a number of dash-separated tokens.
210 | The first token is the CPU type, second is the board type, and third is the board revision.
211 | More tokens can be also added.
212 | 
213 | The bootloader should contain its info file as a static string somewhere in its code.
214 | If possible, the last word of the bootloader code should point to this string.
215 | This way, the info file can be found in the initial section of the `CURRENT.UF2`
216 | file as well. Thus, a board type can be determined from the contents of `CURRENT.UF2`.
217 | This is particularly useful with the source embedding (see above).
218 | 
219 | ## File containers
220 | 
221 | It is also possible to use the UF2 format as a container for one or more
222 | regular files (akin to a TAR file, or ZIP archive without compression).  This
223 | is useful when the embedded device being flashed sports a file system.
224 | 
225 | The program to run may reside in one of the files, or in the main flash memory.
226 | 
227 | In such a usage the `file container` flag is set on blocks, the field `fileSize`
228 | holds the file size of the current file, and the field `targetAddr` holds the
229 | offset in current file.
230 | 
231 | The `not main flash` flag on blocks should be ignored when the `file container` is set.
232 | 
233 | The file name is stored at `&data[payloadSize]` (ie., right after the actual payload) and
234 | terminated with a `0x00` byte.  The format of filename is dependent on the
235 | bootloader (usually implemented as some sort of file system daemon). 
236 | 
237 | The bootloader will usually allow any size of the payload.
238 | 
239 | The current files on device might be exposed as multiple UF2 files, instead of
240 | a single `CURRENT.UF2`. They may reside in directories, however, due to UF2 general
241 | design, it doesn't matter which directory the UF2 file is written to.
242 | 
243 | Typical writing procedure is as follows:
244 | * validate UF2 magic numbers
245 | * make sure that `targetAddr < fileSize` and that `fileSize` isn't out of reasonable range
246 | * write `0x00` at `data[475]` to ensure NUL termination of file name
247 | * read file name from `&data[payloadSize]`; perform any mapping on the file name
248 | * create a directory where the file is to be written if it doesn't exist
249 | * open the file for writing
250 | * truncate the file to `fileSize`
251 | * seek `targetAddr`
252 | * write the payload (ie., `data[0 ... payloadSize - 1]`)
253 | * close the file
254 | 
255 | The fields `blockNo` and `numBlocks` refer to the entire UF2 file, not the current
256 | file.
257 | 
258 | ## MD5 checksum
259 | 
260 | When the `0x4000` flag is set, the last 24 bytes of `data[]` hold the following structure:
261 | 
262 | | Offset | Size | Value                                             |
263 | |--------|------|---------------------------------------------------|
264 | | 0      | 4    | Start address of region                           |
265 | | 4      | 4    | Length of region in bytes                         |
266 | | 8      | 16   | MD5 checksum in binary format                     |
267 | 
268 | The flashing program should compute the MD5 sum of the specified region.
269 | If the region checksum matches, flashing of the current block can be skipped.
270 | Typically, many blocks in sequence will have the same region specified,
271 | and can all be skipped, if the matching succeeded.
272 | The position of the current block will typically be inside of the region.
273 | The position and size of the region should be multiple of page erase size
274 | (4k or 64k on typical SPI flash).
275 | 
276 | This is currently only used on ESP32, which is also why MD5 checksum is used.
277 | 
278 | ## Extension tags
279 | 
280 | When the `0x8000` flag is set, additional information can be appended right after
281 | payload data (i.e., it starts at `32 + payloadSize`).
282 | Every tag starts at 4 byte boundary.
283 | The first byte of tag contains its total size in bytes (including the size byte
284 | and type designation).
285 | The next three bytes designate the type of tag (if you want to define custom
286 | tags, pick them at random).
287 | The last tag has size of `0` and type of `0`.
288 | 
289 | Standard tag designations follow:
290 | * `0x9fc7bc` - version of firmware file - UTF8 semver string
291 | * `0x650d9d` - description of device for which the firmware file is destined (UTF8)
292 | * `0x0be9f7` - page size of target device (32 bit unsigned number)
293 | * `0xb46db0` - SHA-2 checksum of firmware (can be of various size)
294 | * `0xc8a729` - device type identifier - a refinement of `familyID` meant to identify a kind of device
295 |   (eg., a toaster with specific pinout and heating unit), not only MCU; 32 or 64 bit number; can be hash of `0x650d9d`
296 | 
297 | For example, the following bytes encode firmware version `0.1.2` for device
298 | named `ACME Toaster mk3` (line breaks added for clarity):
299 | 
300 | ```
301 | 09 bc c7 9f 30 2e 31 2e 32 00 00 00
302 | 14 9d 0d 65 41 43 4d 45 20 54 6f 61 73 74 65 72 20 6d 6b 33
303 | 00 00 00 00
304 | ```
305 | 
306 | Extension tags can, but don't have to, be repeated in all blocks.
307 | 
308 | ## Implementations
309 | 
310 | ### Bootloaders
311 | 
312 | * [Microchip ATSAMD21 and ATSAMD51](https://github.com/Microsoft/uf2-samdx1)
313 | * [Arduino UNO](https://github.com/mmoskal/uf2-uno)
314 | * [STM32F103](https://github.com/mmoskal/uf2-stm32)
315 | * [STM32F4](https://github.com/mmoskal/uf2-stm32f)
316 | * [Nordic NRF52840](https://github.com/adafruit/Adafruit_nRF52840_Bootloader)
317 | * [Linux (RPi Zero)](https://github.com/microsoft/uf2-linux)
318 | * [Cypress FX2](https://github.com/whitequark/libfx2/tree/master/firmware/boot-uf2)
319 | * [Tiny UF2](https://github.com/adafruit/tinyuf2) - Support ESP32-S2, iMXRT10xx, STM32F4
320 | * [RP2040 chip](https://www.raspberrypi.org/products/raspberry-pi-pico/) - native support in silicon
321 | * [UF2-ChibiOS](https://github.com/striso/uf2-ChibiOS) - Supports STM32H7
322 | 
323 | There's an ongoing effort to implement UF2 in [Codal](https://github.com/lancaster-university/codal-core).
324 | 
325 | ### Editors
326 | 
327 | * https://arcade.makecode.com
328 | * https://makecode.adafruit.com
329 | * https://makecode.seeedstudio.com
330 | * https://maker.makecode.com
331 | 
332 | ### Libraries
333 | 
334 | * https://www.npmjs.com/package/uf2
335 | 
336 | ## License
337 | 
338 | MIT
339 | 
340 | ## Code of Conduct
341 | 
342 | This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.
343 | 


--------------------------------------------------------------------------------
/patcher/patcher.js:
--------------------------------------------------------------------------------
   1 | "use strict";
   2 | 
   3 | // copy entire configkeys.h from https://github.com/microsoft/pxt-common-packages/blob/master/libs/base/configkeys.h
   4 | const CONFIG_KEYS_H =
   5 |     `
   6 | #ifndef __PXT_CONFIGKEYS_H
   7 | #define __PXT_CONFIGKEYS_H
   8 | 
   9 | // used by pins.cpp to mask off the pin name from any config
  10 | // lower 16 pins of value are the pin name
  11 | #define CFG_PIN_NAME_MSK 0x0000ffff
  12 | // upper 16 bits of value is any configuration of the pin.
  13 | #define CFG_PIN_CONFIG_MSK 0xffff0000
  14 | 
  15 | // begin optional pin configurations
  16 | #define CFG_PIN_CONFIG_ACTIVE_LO 0x10000
  17 | 
  18 | 
  19 | #define CFG_MAGIC0 0x1e9e10f1
  20 | #define CFG_MAGIC1 0x20227a79
  21 | 
  22 | // these define keys for getConfig() function
  23 | #define CFG_PIN_ACCELEROMETER_INT 1
  24 | #define CFG_PIN_ACCELEROMETER_SCL 2
  25 | #define CFG_PIN_ACCELEROMETER_SDA 3
  26 | #define CFG_PIN_BTN_A 4
  27 | #define CFG_PIN_BTN_B 5
  28 | #define CFG_PIN_BTN_SLIDE 6
  29 | #define CFG_PIN_DOTSTAR_CLOCK 7
  30 | #define CFG_PIN_DOTSTAR_DATA 8
  31 | #define CFG_PIN_FLASH_CS 9
  32 | #define CFG_PIN_FLASH_MISO 10
  33 | #define CFG_PIN_FLASH_MOSI 11
  34 | #define CFG_PIN_FLASH_SCK 12
  35 | #define CFG_PIN_LED 13
  36 | #define CFG_PIN_LIGHT 14
  37 | #define CFG_PIN_MICROPHONE 15
  38 | #define CFG_PIN_MIC_CLOCK 16
  39 | #define CFG_PIN_MIC_DATA 17
  40 | #define CFG_PIN_MISO 18
  41 | #define CFG_PIN_MOSI 19
  42 | // the preferred pin to drive an external neopixel strip
  43 | #define CFG_PIN_NEOPIXEL 20
  44 | #define CFG_PIN_RX 21
  45 | #define CFG_PIN_RXLED 22
  46 | #define CFG_PIN_SCK 23
  47 | #define CFG_PIN_SCL 24
  48 | #define CFG_PIN_SDA 25
  49 | #define CFG_PIN_SPEAKER_AMP 26
  50 | #define CFG_PIN_TEMPERATURE 27
  51 | #define CFG_PIN_TX 28
  52 | #define CFG_PIN_TXLED 29
  53 | #define CFG_PIN_IR_OUT 30
  54 | #define CFG_PIN_IR_IN 31
  55 | #define CFG_PIN_DISPLAY_SCK 32
  56 | #define CFG_PIN_DISPLAY_MISO 33
  57 | #define CFG_PIN_DISPLAY_MOSI 34
  58 | #define CFG_PIN_DISPLAY_CS 35
  59 | #define CFG_PIN_DISPLAY_DC 36
  60 | #define CFG_DISPLAY_WIDTH 37
  61 | #define CFG_DISPLAY_HEIGHT 38
  62 | #define CFG_DISPLAY_CFG0 39
  63 | #define CFG_DISPLAY_CFG1 40
  64 | #define CFG_DISPLAY_CFG2 41
  65 | #define CFG_DISPLAY_CFG3 42
  66 | #define CFG_PIN_DISPLAY_RST 43
  67 | #define CFG_PIN_DISPLAY_BL 44
  68 | #define CFG_PIN_SERVO_1 45
  69 | #define CFG_PIN_SERVO_2 46
  70 | #define CFG_PIN_BTN_LEFT 47
  71 | #define CFG_PIN_BTN_RIGHT 48
  72 | #define CFG_PIN_BTN_UP 49
  73 | #define CFG_PIN_BTN_DOWN 50
  74 | #define CFG_PIN_BTN_MENU 51
  75 | #define CFG_PIN_LED_R 52
  76 | #define CFG_PIN_LED_G 53
  77 | #define CFG_PIN_LED_B 54
  78 | #define CFG_PIN_LED1 55
  79 | #define CFG_PIN_LED2 56
  80 | #define CFG_PIN_LED3 57
  81 | #define CFG_PIN_LED4 58
  82 | #define CFG_SPEAKER_VOLUME 59
  83 | 
  84 | #define CFG_PIN_JACK_TX 60
  85 | #define CFG_PIN_JACK_SENSE 61
  86 | #define CFG_PIN_JACK_HPEN 62
  87 | #define CFG_PIN_JACK_BZEN 63
  88 | #define CFG_PIN_JACK_PWREN 64
  89 | #define CFG_PIN_JACK_SND 65
  90 | #define CFG_PIN_JACK_BUSLED 66
  91 | #define CFG_PIN_JACK_COMMLED 67
  92 | 
  93 | #define CFG_PIN_BTN_SOFT_RESET 69
  94 | #define CFG_ACCELEROMETER_TYPE 70
  95 | #define CFG_PIN_BTNMX_LATCH 71
  96 | #define CFG_PIN_BTNMX_CLOCK 72
  97 | #define CFG_PIN_BTNMX_DATA 73
  98 | #define CFG_PIN_BTN_MENU2 74
  99 | #define CFG_PIN_BATTSENSE 75
 100 | #define CFG_PIN_VIBRATION 76
 101 | #define CFG_PIN_PWREN 77
 102 | #define CFG_DISPLAY_TYPE 78
 103 | 
 104 | #define CFG_PIN_ROTARY_ENCODER_A 79
 105 | #define CFG_PIN_ROTARY_ENCODER_B 80
 106 | 
 107 | #define CFG_ACCELEROMETER_SPACE 81
 108 | 
 109 | #define CFG_PIN_WIFI_MOSI 82
 110 | #define CFG_PIN_WIFI_MISO 83
 111 | #define CFG_PIN_WIFI_SCK 84
 112 | #define CFG_PIN_WIFI_TX 85
 113 | #define CFG_PIN_WIFI_RX 86
 114 | #define CFG_PIN_WIFI_CS 87
 115 | #define CFG_PIN_WIFI_BUSY 88
 116 | #define CFG_PIN_WIFI_RESET 89
 117 | #define CFG_PIN_WIFI_GPIO0 90
 118 | #define CFG_PIN_WIFI_AT_TX 91
 119 | #define CFG_PIN_WIFI_AT_RX 92
 120 | 
 121 | #define CFG_PIN_USB_POWER 93
 122 | 
 123 | // default I2C address
 124 | #define ACCELEROMETER_TYPE_LIS3DH 0x32
 125 | #define ACCELEROMETER_TYPE_LIS3DH_ALT 0x30
 126 | #define ACCELEROMETER_TYPE_MMA8453 0x38
 127 | #define ACCELEROMETER_TYPE_FXOS8700 0x3C
 128 | #define ACCELEROMETER_TYPE_MMA8653 0x3A
 129 | #define ACCELEROMETER_TYPE_MSA300 0x4C
 130 | #define ACCELEROMETER_TYPE_MPU6050 0x68
 131 | 
 132 | #define DISPLAY_TYPE_ST7735 7735
 133 | #define DISPLAY_TYPE_ILI9341 9341
 134 | #define DISPLAY_TYPE_SMART 4242
 135 | 
 136 | #define CFG_PIN_A0 100
 137 | #define CFG_PIN_A1 101
 138 | #define CFG_PIN_A2 102
 139 | #define CFG_PIN_A3 103
 140 | #define CFG_PIN_A4 104
 141 | #define CFG_PIN_A5 105
 142 | #define CFG_PIN_A6 106
 143 | #define CFG_PIN_A7 107
 144 | #define CFG_PIN_A8 108
 145 | #define CFG_PIN_A9 109
 146 | #define CFG_PIN_A10 110
 147 | #define CFG_PIN_A11 111
 148 | #define CFG_PIN_A12 112
 149 | #define CFG_PIN_A13 113
 150 | #define CFG_PIN_A14 114
 151 | #define CFG_PIN_A15 115
 152 | #define CFG_PIN_A16 116
 153 | #define CFG_PIN_A17 117
 154 | #define CFG_PIN_A18 118
 155 | #define CFG_PIN_A19 119
 156 | #define CFG_PIN_A20 120
 157 | #define CFG_PIN_A21 121
 158 | #define CFG_PIN_A22 122
 159 | #define CFG_PIN_A23 123
 160 | #define CFG_PIN_A24 124
 161 | #define CFG_PIN_A25 125
 162 | #define CFG_PIN_A26 126
 163 | #define CFG_PIN_A27 127
 164 | #define CFG_PIN_A28 128
 165 | #define CFG_PIN_A29 129
 166 | #define CFG_PIN_A30 130
 167 | #define CFG_PIN_A31 131
 168 | 
 169 | #define CFG_PIN_D0 150
 170 | #define CFG_PIN_D1 151
 171 | #define CFG_PIN_D2 152
 172 | #define CFG_PIN_D3 153
 173 | #define CFG_PIN_D4 154
 174 | #define CFG_PIN_D5 155
 175 | #define CFG_PIN_D6 156
 176 | #define CFG_PIN_D7 157
 177 | #define CFG_PIN_D8 158
 178 | #define CFG_PIN_D9 159
 179 | #define CFG_PIN_D10 160
 180 | #define CFG_PIN_D11 161
 181 | #define CFG_PIN_D12 162
 182 | #define CFG_PIN_D13 163
 183 | #define CFG_PIN_D14 164
 184 | #define CFG_PIN_D15 165
 185 | #define CFG_PIN_D16 166
 186 | #define CFG_PIN_D17 167
 187 | #define CFG_PIN_D18 168
 188 | #define CFG_PIN_D19 169
 189 | #define CFG_PIN_D20 170
 190 | #define CFG_PIN_D21 171
 191 | #define CFG_PIN_D22 172
 192 | #define CFG_PIN_D23 173
 193 | #define CFG_PIN_D24 174
 194 | #define CFG_PIN_D25 175
 195 | #define CFG_PIN_D26 176
 196 | #define CFG_PIN_D27 177
 197 | #define CFG_PIN_D28 178
 198 | #define CFG_PIN_D29 179
 199 | #define CFG_PIN_D30 180
 200 | #define CFG_PIN_D31 181
 201 | 
 202 | #define CFG_NUM_NEOPIXELS 200
 203 | #define CFG_NUM_DOTSTARS 201
 204 | #define CFG_DEFAULT_BUTTON_MODE 202
 205 | #define CFG_SWD_ENABLED 203
 206 | #define CFG_FLASH_BYTES 204
 207 | #define CFG_RAM_BYTES 205
 208 | #define CFG_SYSTEM_HEAP_BYTES 206
 209 | #define CFG_LOW_MEM_SIMULATION_KB 207
 210 | #define CFG_BOOTLOADER_BOARD_ID 208
 211 | #define CFG_UF2_FAMILY 209
 212 | #define CFG_PINS_PORT_SIZE 210
 213 | #define CFG_BOOTLOADER_PROTECTION 211
 214 | #define CFG_POWER_DEEPSLEEP_TIMEOUT 212
 215 | #define CFG_ANALOG_BUTTON_THRESHOLD 213
 216 | #define CFG_CPU_MHZ 214
 217 | #define CFG_CONTROLLER_LIGHT_MAX_BRIGHTNESS 215
 218 | #define CFG_ANALOG_JOYSTICK_MIN 216
 219 | #define CFG_ANALOG_JOYSTICK_MAX 217
 220 | #define CFG_TIMERS_TO_USE 218
 221 | // configs to specify the onboard (built-in) dotstar or neopixel strips
 222 | // some boards have a combination of dotstar, neopixel strips like neotrellis
 223 | #define CFG_PIN_ONBOARD_DOTSTAR_CLOCK 219
 224 | #define CFG_PIN_ONBOARD_DOTSTAR_DATA 220
 225 | #define CFG_NUM_ONBOARD_DOTSTARS 221
 226 | #define CFG_PIN_ONBOARD_NEOPIXEL 222
 227 | #define CFG_NUM_ONBOARD_NEOPIXELS 223
 228 | 
 229 | #define CFG_MATRIX_KEYPAD_MESSAGE_ID 239
 230 | #define CFG_NUM_MATRIX_KEYPAD_ROWS 240
 231 | #define CFG_PIN_MATRIX_KEYPAD_ROW0 241
 232 | #define CFG_PIN_MATRIX_KEYPAD_ROW1 242
 233 | #define CFG_PIN_MATRIX_KEYPAD_ROW2 243
 234 | #define CFG_PIN_MATRIX_KEYPAD_ROW3 244
 235 | #define CFG_PIN_MATRIX_KEYPAD_ROW4 245
 236 | #define CFG_PIN_MATRIX_KEYPAD_ROW5 246
 237 | #define CFG_PIN_MATRIX_KEYPAD_ROW6 247
 238 | #define CFG_PIN_MATRIX_KEYPAD_ROW7 248
 239 | #define CFG_NUM_MATRIX_KEYPAD_COLS 250
 240 | #define CFG_PIN_MATRIX_KEYPAD_COL0 251
 241 | #define CFG_PIN_MATRIX_KEYPAD_COL1 252
 242 | #define CFG_PIN_MATRIX_KEYPAD_COL2 253
 243 | #define CFG_PIN_MATRIX_KEYPAD_COL3 254
 244 | #define CFG_PIN_MATRIX_KEYPAD_COL4 255
 245 | #define CFG_PIN_MATRIX_KEYPAD_COL5 256
 246 | #define CFG_PIN_MATRIX_KEYPAD_COL6 257
 247 | #define CFG_PIN_MATRIX_KEYPAD_COL7 258
 248 | 
 249 | #define CFG_PIN_B0 300
 250 | #define CFG_PIN_B1 301
 251 | #define CFG_PIN_B2 302
 252 | #define CFG_PIN_B3 303
 253 | #define CFG_PIN_B4 304
 254 | #define CFG_PIN_B5 305
 255 | #define CFG_PIN_B6 306
 256 | #define CFG_PIN_B7 307
 257 | #define CFG_PIN_B8 308
 258 | #define CFG_PIN_B9 309
 259 | #define CFG_PIN_B10 310
 260 | #define CFG_PIN_B11 311
 261 | #define CFG_PIN_B12 312
 262 | #define CFG_PIN_B13 313
 263 | #define CFG_PIN_B14 314
 264 | #define CFG_PIN_B15 315
 265 | #define CFG_PIN_B16 316
 266 | #define CFG_PIN_B17 317
 267 | #define CFG_PIN_B18 318
 268 | #define CFG_PIN_B19 319
 269 | #define CFG_PIN_B20 320
 270 | #define CFG_PIN_B21 321
 271 | #define CFG_PIN_B22 322
 272 | #define CFG_PIN_B23 323
 273 | #define CFG_PIN_B24 324
 274 | #define CFG_PIN_B25 325
 275 | #define CFG_PIN_B26 326
 276 | #define CFG_PIN_B27 327
 277 | #define CFG_PIN_B28 328
 278 | #define CFG_PIN_B29 329
 279 | #define CFG_PIN_B30 330
 280 | #define CFG_PIN_B31 331
 281 | 
 282 | #define CFG_PIN_C0 350
 283 | #define CFG_PIN_C1 351
 284 | #define CFG_PIN_C2 352
 285 | #define CFG_PIN_C3 353
 286 | #define CFG_PIN_C4 354
 287 | #define CFG_PIN_C5 355
 288 | #define CFG_PIN_C6 356
 289 | #define CFG_PIN_C7 357
 290 | #define CFG_PIN_C8 358
 291 | #define CFG_PIN_C9 359
 292 | #define CFG_PIN_C10 360
 293 | #define CFG_PIN_C11 361
 294 | #define CFG_PIN_C12 362
 295 | #define CFG_PIN_C13 363
 296 | #define CFG_PIN_C14 364
 297 | #define CFG_PIN_C15 365
 298 | #define CFG_PIN_C16 366
 299 | #define CFG_PIN_C17 367
 300 | #define CFG_PIN_C18 368
 301 | #define CFG_PIN_C19 369
 302 | #define CFG_PIN_C20 370
 303 | #define CFG_PIN_C21 371
 304 | #define CFG_PIN_C22 372
 305 | #define CFG_PIN_C23 373
 306 | #define CFG_PIN_C24 374
 307 | #define CFG_PIN_C25 375
 308 | #define CFG_PIN_C26 376
 309 | #define CFG_PIN_C27 377
 310 | #define CFG_PIN_C28 378
 311 | #define CFG_PIN_C29 379
 312 | #define CFG_PIN_C30 380
 313 | #define CFG_PIN_C31 381
 314 | 
 315 | #define CFG_PIN_P0 400
 316 | #define CFG_PIN_P1 401
 317 | #define CFG_PIN_P2 402
 318 | #define CFG_PIN_P3 403
 319 | #define CFG_PIN_P4 404
 320 | #define CFG_PIN_P5 405
 321 | #define CFG_PIN_P6 406
 322 | #define CFG_PIN_P7 407
 323 | #define CFG_PIN_P8 408
 324 | #define CFG_PIN_P9 409
 325 | #define CFG_PIN_P10 410
 326 | #define CFG_PIN_P11 411
 327 | #define CFG_PIN_P12 412
 328 | #define CFG_PIN_P13 413
 329 | #define CFG_PIN_P14 414
 330 | #define CFG_PIN_P15 415
 331 | #define CFG_PIN_P16 416
 332 | #define CFG_PIN_P17 417
 333 | #define CFG_PIN_P18 418
 334 | #define CFG_PIN_P19 419
 335 | #define CFG_PIN_P20 420
 336 | #define CFG_PIN_P21 421
 337 | #define CFG_PIN_P22 422
 338 | #define CFG_PIN_P23 423
 339 | #define CFG_PIN_P24 424
 340 | #define CFG_PIN_P25 425
 341 | #define CFG_PIN_P26 426
 342 | #define CFG_PIN_P27 427
 343 | #define CFG_PIN_P28 428
 344 | #define CFG_PIN_P29 429
 345 | #define CFG_PIN_P30 430
 346 | #define CFG_PIN_P31 431
 347 | #define CFG_PIN_P32 432
 348 | #define CFG_PIN_P33 433
 349 | #define CFG_PIN_P34 434
 350 | #define CFG_PIN_P35 435
 351 | #define CFG_PIN_P36 436
 352 | #define CFG_PIN_P37 437
 353 | #define CFG_PIN_P38 438
 354 | #define CFG_PIN_P39 439
 355 | #define CFG_PIN_P40 440
 356 | #define CFG_PIN_P41 441
 357 | #define CFG_PIN_P42 442
 358 | #define CFG_PIN_P43 443
 359 | #define CFG_PIN_P44 444
 360 | #define CFG_PIN_P45 445
 361 | #define CFG_PIN_P46 446
 362 | #define CFG_PIN_P47 447
 363 | #define CFG_PIN_P48 448
 364 | #define CFG_PIN_P49 449
 365 | #define CFG_PIN_P50 450
 366 | #define CFG_PIN_P51 451
 367 | #define CFG_PIN_P52 452
 368 | #define CFG_PIN_P53 453
 369 | #define CFG_PIN_P54 454
 370 | #define CFG_PIN_P55 455
 371 | #define CFG_PIN_P56 456
 372 | #define CFG_PIN_P57 457
 373 | #define CFG_PIN_P58 458
 374 | #define CFG_PIN_P59 459
 375 | #define CFG_PIN_P60 460
 376 | #define CFG_PIN_P61 461
 377 | #define CFG_PIN_P62 462
 378 | #define CFG_PIN_P63 463
 379 | 
 380 | #define CFG_PIN_LORA_MISO 1001
 381 | #define CFG_PIN_LORA_MOSI 1002
 382 | #define CFG_PIN_LORA_SCK 1003
 383 | #define CFG_PIN_LORA_CS 1004
 384 | #define CFG_PIN_LORA_BOOT 1005
 385 | #define CFG_PIN_LORA_RESET 1006
 386 | #define CFG_PIN_IRRXLED 1007
 387 | #define CFG_PIN_IRTXLED 1008
 388 | #define CFG_PIN_LCD_RESET 1009
 389 | #define CFG_PIN_LCD_ENABLE 1010
 390 | #define CFG_PIN_LCD_DATALINE4 1011
 391 | #define CFG_PIN_LCD_DATALINE5 1012
 392 | #define CFG_PIN_LCD_DATALINE6 1013
 393 | #define CFG_PIN_LCD_DATALINE7 1014
 394 | #define CFG_NUM_LCD_COLUMNS 1015
 395 | #define CFG_NUM_LCD_ROWS 1016
 396 | 
 397 | //RoboHAT MM1 pinout
 398 | #define CFG_PIN_RCC0 1017
 399 | #define CFG_PIN_RCC1 1018
 400 | #define CFG_PIN_RCC2 1019
 401 | #define CFG_PIN_RCC3 1020
 402 | #define CFG_PIN_RCC4 1021
 403 | #define CFG_PIN_RCC5 1022
 404 | #define CFG_PIN_RCC6 1023
 405 | #define CFG_PIN_RCC7 1024
 406 | #define CFG_PIN_SERVO0 1025
 407 | #define CFG_PIN_SERVO1 1026
 408 | #define CFG_PIN_SERVO2 1027
 409 | #define CFG_PIN_SERVO3 1028
 410 | #define CFG_PIN_SERVO4 1029
 411 | #define CFG_PIN_SERVO5 1030
 412 | #define CFG_PIN_SERVO6 1031
 413 | #define CFG_PIN_SERVO7 1032
 414 | #define CFG_PIN_SERVO8 1033
 415 | #define CFG_PIN_PI_TX 1034
 416 | #define CFG_PIN_PI_RX 1035
 417 | #define CFG_PIN_GPS_SDA 1036
 418 | #define CFG_PIN_GPS_SCL 1037
 419 | #define CFG_PIN_GPS_TX 1038
 420 | #define CFG_PIN_GPS_RX 1039
 421 | #define CFG_PIN_GROVE0 1040
 422 | #define CFG_PIN_GROVE1 1041
 423 | #define CFG_PIN_SS 1042
 424 | 
 425 | // Adafruit Grand Central M4
 426 | #define CFG_PIN_D33 183
 427 | #define CFG_PIN_D34 184
 428 | #define CFG_PIN_D35 185
 429 | #define CFG_PIN_D36 186
 430 | #define CFG_PIN_D37 187
 431 | #define CFG_PIN_D38 188
 432 | #define CFG_PIN_D39 189
 433 | #define CFG_PIN_D40 190
 434 | #define CFG_PIN_D41 191
 435 | #define CFG_PIN_D42 192
 436 | #define CFG_PIN_D43 193
 437 | #define CFG_PIN_D44 194
 438 | #define CFG_PIN_D45 195
 439 | #define CFG_PIN_D46 196
 440 | #define CFG_PIN_D47 197
 441 | #define CFG_PIN_D48 198
 442 | #define CFG_PIN_D49 199
 443 | #define CFG_PIN_D50 259
 444 | #define CFG_PIN_D51 260
 445 | #define CFG_PIN_D52 261
 446 | #define CFG_PIN_D53 262
 447 | 
 448 | #define CFG_PIN_TX1 263
 449 | #define CFG_PIN_TX2 264
 450 | #define CFG_PIN_TX3 265
 451 | #define CFG_PIN_RX1 266
 452 | #define CFG_PIN_RX2 267
 453 | #define CFG_PIN_RX3 268
 454 | #define CFG_PIN_SCL1 269
 455 | #define CFG_PIN_SDA1 270
 456 | #define CFG_PIN_PCC_D0 271
 457 | #define CFG_PIN_PCC_D1 272
 458 | #define CFG_PIN_PCC_D2 273
 459 | #define CFG_PIN_PCC_D3 274
 460 | #define CFG_PIN_PCC_D4 275
 461 | #define CFG_PIN_PCC_D5 276
 462 | #define CFG_PIN_PCC_D6 277
 463 | #define CFG_PIN_PCC_D7 278
 464 | #define CFG_PIN_PCC_D8 279
 465 | #define CFG_PIN_PCC_D9 280
 466 | #define CFG_PIN_PCC_D10 281
 467 | #define CFG_PIN_PCC_D11 282
 468 | #define CFG_PIN_PCC_D12 283
 469 | #define CFG_PIN_PCC_D13 284
 470 | #define CFG_PIN_CC_DEN1 285
 471 | #define CFG_PIN_CC_DEN2 286
 472 | #define CFG_PIN_CC_CLK 287
 473 | #define CFG_PIN_XCC_CLK 288
 474 | 
 475 | 
 476 | #define CFG_PIN_JDPWR_PRE_SENSE 1100
 477 | #define CFG_PIN_JDPWR_GND_SENSE 1101
 478 | #define CFG_PIN_JDPWR_PULSE 1102
 479 | #define CFG_PIN_JDPWR_OVERLOAD_LED 1103
 480 | #define CFG_PIN_JDPWR_ENABLE 1104
 481 | #define CFG_PIN_JDPWR_FAULT 1105
 482 | 
 483 | #endif
 484 | `
 485 | 
 486 | const configKeys = {}
 487 | CONFIG_KEYS_H.replace(/#define\s+CFG_(\w+)\s+(\w+)/g, function (m, name, value) {
 488 |     configKeys[name] = parseInt(value);
 489 |     return "";
 490 | })
 491 | 
 492 | const enums = {
 493 |     // these are the same as the default I2C ID
 494 |     ACCELEROMETER_TYPE: {
 495 |         LIS3DH: 0x32,
 496 |         LIS3DH_ALT: 0x30,
 497 |         MMA8453: 0x38,
 498 |         FXOS8700: 0x3C,
 499 |         MMA8653: 0x3A,
 500 |         MSA300: 0x4C,
 501 |         MPU6050: 0x68,
 502 |     },
 503 |     UF2_FAMILY: {
 504 |         ATSAMD21: 0x68ed2b88,
 505 |         ATSAML21: 0x1851780a,
 506 |         ATSAMD51: 0x55114460,
 507 |         NRF52840: 0x1b57745f,
 508 |         STM32F103: 0x5ee21072,
 509 |         STM32F401: 0x57755a57,
 510 |         ATMEGA32: 0x16573617,
 511 |         CYPRESS_FX2: 0x5a18069b,
 512 |     },
 513 |     PINS_PORT_SIZE: {
 514 |         PA_16: 0x10, // PA00-PA15, PB00-PB15, ... - STM32
 515 |         PA_32: 0x20, // PA00-PA31, ... - ATSAMD
 516 |         P0_16: 0x1010, // P0_0-P0_15, P1_0-P1_15, ...
 517 |         P0_32: 0x1020, // P0_0-P0_32, ... - NRF
 518 |     },
 519 |     DEFAULT_BUTTON_MODE: {
 520 |         ACTIVE_HIGH_PULL_DOWN: 0x11,
 521 |         ACTIVE_HIGH_PULL_UP: 0x21,
 522 |         ACTIVE_HIGH_PULL_NONE: 0x31,
 523 |         ACTIVE_LOW_PULL_DOWN: 0x10,
 524 |         ACTIVE_LOW_PULL_UP: 0x20,
 525 |         ACTIVE_LOW_PULL_NONE: 0x30,
 526 |     },
 527 |     DISPLAY_TYPE: {
 528 |         ST7735: 7735,
 529 |         ILI9341: 9341,
 530 |     },
 531 |     ".": {
 532 |         BTN_FLAG_ACTIVE_HIGH: 0x110000,
 533 |         BTN_FLAG_ACTIVE_LOW: 0x200000,
 534 |         BTN_OFFSET_ANALOG_PLUS: 1100,
 535 |         BTN_OFFSET_ANALOG_MINUS: 1200,
 536 |     }
 537 | }
 538 | 
 539 | 
 540 | let infoMsg = ""
 541 | 
 542 | function log(msg) {
 543 |     msg = "# " + msg
 544 |     infoMsg += msg + "\n"
 545 |     console.log(msg)
 546 | }
 547 | 
 548 | function help() {
 549 |     console.log(`
 550 | USAGE: node patch-cfg.js file.uf2 [patch.cf2]
 551 | 
 552 | Without .cf2 file, it will parse config in the UF2 file and print it out
 553 | (in .cf2 format).
 554 | 
 555 | With .cf2 file, it will patch in-place the UF2 file with specified config.
 556 | `)
 557 |     process.exit(1)
 558 | }
 559 | 
 560 | function readBin(fn) {
 561 |     const fs = require("fs")
 562 | 
 563 |     if (!fn) {
 564 |         console.log("Required argument missing.")
 565 |         help()
 566 |     }
 567 | 
 568 |     try {
 569 |         return fs.readFileSync(fn)
 570 |     } catch (e) {
 571 |         console.log("Cannot read file '" + fn + "': " + e.message)
 572 |         help()
 573 |     }
 574 | }
 575 | const configInvKeys = {}
 576 | 
 577 | const UF2_MAGIC_START0 = 0x0A324655 // "UF2\n"
 578 | const UF2_MAGIC_START1 = 0x9E5D5157 // Randomly selected
 579 | const UF2_MAGIC_END = 0x0AB16F30 // Ditto
 580 | 
 581 | const CFG_MAGIC0 = 0x1e9e10f1
 582 | const CFG_MAGIC1 = 0x20227a79
 583 | 
 584 | let all_defines = {}
 585 | 
 586 | function configkeysH() {
 587 |     let r = "#ifndef __CONFIGKEYS_H\n#define __CONFIGKEYS_H 1\n\n"
 588 | 
 589 |     const add = (k, v) => {
 590 |         all_defines[k] = v
 591 |         if (v > 1000 || !/^CFG_/.test(k))
 592 |             v = "0x" + v.toString(16)
 593 |         else
 594 |             v += ""
 595 |         r += "#define " + k + " " + v + "\n"
 596 |     }
 597 | 
 598 |     add("CFG_MAGIC0", CFG_MAGIC0)
 599 |     add("CFG_MAGIC1", CFG_MAGIC1)
 600 |     r += "\n"
 601 | 
 602 |     for (let k of Object.keys(configKeys)) {
 603 |         add("CFG_" + k, configKeys[k])
 604 |     }
 605 |     for (let k of Object.keys(enums)) {
 606 |         r += "\n"
 607 |         for (let kk of Object.keys(enums[k])) {
 608 |             let n = k == "." ? kk : `${k}_${kk}`
 609 |             add(n, enums[k][kk])
 610 |         }
 611 |     }
 612 |     r += "\n#endif // __CONFIGKEYS_H\n"
 613 |     return r
 614 | }
 615 | 
 616 | function err(msg) {
 617 |     log("Fatal error: " + msg)
 618 |     if (typeof window == "undefined") {
 619 |         process.exit(1)
 620 |     } else {
 621 |         throw new Error(msg)
 622 |     }
 623 | }
 624 | 
 625 | function read32(buf, off) {
 626 |     return (buf[off + 0] | (buf[off + 1] << 8) | (buf[off + 2] << 16) | (buf[off + 3] << 24)) >>> 0
 627 | }
 628 | 
 629 | function write32(buf, off, v) {
 630 |     buf[off + 0] = v & 0xff
 631 |     buf[off + 1] = (v >> 8) & 0xff
 632 |     buf[off + 2] = (v >> 16) & 0xff
 633 |     buf[off + 3] = (v >> 24) & 0xff
 634 | }
 635 | 
 636 | function patchHFile(file, patch) {
 637 |     configkeysH()
 638 |     let resFile = ""
 639 |     let inZone = false
 640 |     let flags = {}
 641 |     let lineNo = 0
 642 |     let nums = []
 643 |     for (let line0 of file.split(/\n/)) {
 644 |         lineNo++
 645 |         let append = line0 + "\n"
 646 |         let line = line0.trim().replace(/\/\/.*/, "")
 647 |         if (inZone) {
 648 |             if (line.indexOf("/* CF2 END */") >= 0) {
 649 |                 inZone = false
 650 |                 if (patch) {
 651 |                     let portSize = lookupCfg(patch, configKeys.PINS_PORT_SIZE)
 652 |                     let s = ""
 653 |                     let size = flags["size"] || 100
 654 |                     let numentries = patch.length >> 1
 655 |                     size = Math.max(size, numentries + 4)
 656 |                     s += `    ${CFG_MAGIC0}, ${CFG_MAGIC1}, // magic\n`
 657 |                     s += `    ${numentries}, ${size},  // used entries, total entries\n`
 658 |                     for (let i = 0; i < numentries; ++i) {
 659 |                         let k = patch[i * 2]
 660 |                         let v = patch[i * 2 + 1]
 661 |                         s += `    ${k}, 0x${v.toString(16)}, // ${showKV(k, v, portSize, patch)}\n`
 662 |                     }
 663 |                     s += "   "
 664 |                     for (let i = 0; i < size - numentries; ++i) {
 665 |                         if (i && i % 16 == 0)
 666 |                             s += "\n   "
 667 |                         s += " 0, 0,"
 668 |                     }
 669 |                     s += "\n"
 670 |                     append = s + line0 + "\n"
 671 |                 }
 672 |             } else {
 673 |                 append = ""
 674 |                 let toks = line.split(/,\s*/).map(s => s.trim()).filter(s => !!s)
 675 |                 for (let tok of toks) {
 676 |                     let n = parseInt(tok)
 677 |                     if (isNaN(n)) {
 678 |                         n = all_defines[tok]
 679 |                         if (n === undefined) {
 680 |                             let portSize = lookupCfg(nums, configKeys.PINS_PORT_SIZE)
 681 |                             if (portSize) portSize &= 0xfff;
 682 |                             let pp = parsePinName(tok.replace(/^PIN_/, ""), portSize)
 683 |                             if (pp !== undefined) {
 684 |                                 n = pp
 685 |                             } else {
 686 |                                 err(`unknown value ${tok} at line ${lineNo}`)
 687 |                             }
 688 |                         }
 689 |                     }
 690 |                     nums.push(n)
 691 |                 }
 692 |             }
 693 |         } else {
 694 |             let m = /\/\* CF2 START (.*)/.exec(line)
 695 |             if (m) {
 696 |                 inZone = true
 697 |                 for (let k of m[1].split(/\s+/)) {
 698 |                     let mm = /^(\w+)=(\d+)$/.exec(k)
 699 |                     if (mm)
 700 |                         flags[mm[1]] = parseInt(mm[2])
 701 |                     else
 702 |                         flags[k] = true
 703 |                 }
 704 |             }
 705 |         }
 706 |         resFile += append
 707 |     }
 708 | 
 709 |     if (nums.length) {
 710 |         if (nums[0] != CFG_MAGIC0 || nums[1] != CFG_MAGIC1)
 711 |             err("no magic in H file")
 712 |         nums = nums.slice(4)
 713 |         for (let i = 0; i < nums.length; i += 2) {
 714 |             if (nums[i] == 0) {
 715 |                 if (nums.slice(i).some(x => x != 0))
 716 |                     err("config keys follow zero terminator")
 717 |                 else
 718 |                     nums = nums.slice(0, i)
 719 |                 break
 720 |             }
 721 |         }
 722 |     }
 723 | 
 724 |     return {
 725 |         patched: resFile,
 726 |         data: nums
 727 |     }
 728 | }
 729 | 
 730 | function bufToString(buf) {
 731 |     let s = ""
 732 |     for (let i = 0; i < buf.length; ++i)
 733 |         s += String.fromCharCode(buf[i])
 734 |     return s
 735 | }
 736 | 
 737 | function stringToBuf(str) {
 738 |     let buf = new Uint8Array(str.length)
 739 |     for (let i = 0; i < buf.length; ++i)
 740 |         buf[i] = str.charCodeAt(i)
 741 |     return buf
 742 | }
 743 | 
 744 | function readWriteConfig(buf, patch) {
 745 |     let patchPtr = null
 746 |     let origData = []
 747 |     let cfgLen = 0
 748 |     let isUF2 = false
 749 |     if (read32(buf, 0) == UF2_MAGIC_START0) {
 750 |         isUF2 = true
 751 |         log("detected UF2 file")
 752 |     } else {
 753 |         let stackBase = read32(buf, 0)
 754 |         if ((stackBase & 0xff000003) == 0x20000000 &&
 755 |             (read32(buf, 4) & 1) == 1) {
 756 |             log("detected BIN file")
 757 |         } else {
 758 |             let str = bufToString(buf)
 759 |             if (str.indexOf("/* CF2 START") >= 0) {
 760 |                 log("detected CF2 header file")
 761 |                 let rr = patchHFile(str, patch)
 762 |                 console.log(rr.data)
 763 |                 return patch ? stringToBuf(rr.patched) : rr.data
 764 |             } else {
 765 |                 err("unknown file format")
 766 |             }
 767 |         }
 768 |     }
 769 |     if (patch)
 770 |         patch.push(0, 0)
 771 |     for (let off = 0; off < buf.length; off += 512) {
 772 |         let start = 0
 773 |         let payloadLen = 512
 774 |         let addr = off
 775 | 
 776 |         if (isUF2) {
 777 |             start = 32
 778 |             if (read32(buf, off) != UF2_MAGIC_START0 ||
 779 |                 read32(buf, off + 4) != UF2_MAGIC_START1) {
 780 |                 err("invalid data at " + off)
 781 |             }
 782 |             payloadLen = read32(buf, off + 16)
 783 |             addr = read32(buf, off + 12) - 32
 784 |         }
 785 | 
 786 |         for (let i = start; i < start + payloadLen; i += 4) {
 787 |             if (read32(buf, off + i) == CFG_MAGIC0 &&
 788 |                 read32(buf, off + i + 4) == CFG_MAGIC1) {
 789 |                 let addrS = "0x" + (addr + i).toString(16)
 790 |                 if (patchPtr === null) {
 791 |                     log(`Found CFG DATA at ${addrS}`)
 792 |                     patchPtr = -4
 793 |                 } else {
 794 |                     if (patch) {
 795 |                         log(`Also patching at ${addrS}`)
 796 |                         patchPtr = -4
 797 |                     } else {
 798 |                         log(`Skipping second CFG DATA at ${addrS}`)
 799 |                     }
 800 |                 }
 801 |             }
 802 | 
 803 |             if (patchPtr !== null) {
 804 |                 if (patchPtr == -2) {
 805 |                     cfgLen = read32(buf, off + i)
 806 |                     if (patch)
 807 |                         write32(buf, off + i, (patch.length >> 1) - 1)
 808 |                 }
 809 | 
 810 |                 if (patchPtr >= 0) {
 811 |                     if (origData.length < cfgLen * 2 + 40)
 812 |                         origData.push(read32(buf, off + i))
 813 |                     if (patch) {
 814 |                         if (patchPtr < patch.length) {
 815 |                             write32(buf, off + i, patch[patchPtr])
 816 |                         }
 817 |                     }
 818 |                 }
 819 |                 patchPtr++
 820 |             }
 821 |         }
 822 |     }
 823 | 
 824 |     let len0 = cfgLen * 2
 825 |     origData.push(0, 0)
 826 |     while (origData[len0])
 827 |         len0 += 2
 828 |     origData = origData.slice(0, len0 + 2)
 829 |     if (len0 != cfgLen * 2)
 830 |         log("size information incorrect; continuing anyway")
 831 | 
 832 |     if (origData.length == 0)
 833 |         err("config data not found")
 834 |     if (patch && patchPtr < patch.length)
 835 |         err("no space for config data")
 836 |     let tail = origData.slice(origData.length - 2)
 837 |     if (tail.some(x => x != 0))
 838 |         err("config data not zero terminated: " + tail.join(","))
 839 |     origData = origData.slice(0, origData.length - 2)
 840 |     return patch ? buf : origData
 841 | }
 842 | 
 843 | function lookupCfg(cfgdata, key) {
 844 |     for (let i = 0; i < cfgdata.length; i += 2)
 845 |         if (cfgdata[i] == key)
 846 |             return cfgdata[i + 1]
 847 |     return null
 848 | }
 849 | 
 850 | function pinToString(pinNo, portSize) {
 851 |     if (!portSize || pinNo >= 1000)
 852 |         return "P_" + pinNo
 853 | 
 854 |     let useLetters = true
 855 |     let theSize = portSize & 0xfff
 856 |     if (portSize & 0x1000) {
 857 |         useLetters = true
 858 |     }
 859 |     let port = (pinNo / theSize) | 0
 860 |     let pin = pinNo % theSize
 861 |     if (useLetters) {
 862 |         return "P" + String.fromCharCode(65 + port) + ("0" + pin.toString()).slice(-2)
 863 |     } else {
 864 |         return "P" + port + "_" + pin
 865 |     }
 866 | }
 867 | 
 868 | function isHeaderPin(n) {
 869 |     return /^PIN_(MOSI|MISO|SCK|SDA|SCL|RX|TX|[AD]\d+)$/.test(n)
 870 | }
 871 | 
 872 | function keyWeight(k) {
 873 |     if (k == "PINS_PORT_SIZE")
 874 |         return 10
 875 |     if (isHeaderPin(k))
 876 |         return 20
 877 |     if (/^PIN_/.test(k))
 878 |         return 30
 879 |     return 40
 880 | }
 881 | 
 882 | function expandNum(k) {
 883 |     return k.replace(/\d+/g, f => {
 884 |         if (f.length > 4)
 885 |             return f
 886 |         return ("0000" + f).slice(-4)
 887 |     })
 888 | }
 889 | 
 890 | function cmpKeys(a, b) {
 891 |     a = a.replace(/ =.*/, "")
 892 |     b = b.replace(/ =.*/, "")
 893 |     if (a == b)
 894 |         return 0
 895 |     let d = keyWeight(a) - keyWeight(b)
 896 |     if (d) return d
 897 |     let aa = expandNum(a)
 898 |     let bb = expandNum(b)
 899 |     if (aa < bb) return -1
 900 |     else if (bb < aa) return 1
 901 |     else if (a < b) return -1
 902 |     else return 1
 903 | }
 904 | 
 905 | function showKV(k, v, portSize, data) {
 906 |     let vn = ""
 907 | 
 908 |     let kn = configInvKeys[k + ""] || ""
 909 | 
 910 |     if (enums[kn]) {
 911 |         for (let en of Object.keys(enums[kn])) {
 912 |             if (enums[kn][en] == v) {
 913 |                 vn = en
 914 |                 break
 915 |             }
 916 |         }
 917 |     }
 918 | 
 919 |     if (vn == "") {
 920 |         if (/_CFG/.test(kn) || v > 10000)
 921 |             vn = "0x" + v.toString(16)
 922 |         else if (/^PIN_/.test(kn)) {
 923 |             if (data && !isHeaderPin(kn)) {
 924 |                 for (let pn of Object.keys(configKeys)) {
 925 |                     if (isHeaderPin(pn) && lookupCfg(data, configKeys[pn]) === v) {
 926 |                         vn = pn
 927 |                         break
 928 |                     }
 929 |                 }
 930 |             }
 931 |             if (!vn)
 932 |                 vn = pinToString(v, portSize)
 933 |         } else
 934 |             vn = v + ""
 935 |     }
 936 | 
 937 |     if (kn == "")
 938 |         kn = "_" + k
 939 | 
 940 |     return `${kn} = ${vn}`
 941 | }
 942 | 
 943 | function readConfig(buf) {
 944 |     init()
 945 |     let cfgdata = readWriteConfig(buf, null)
 946 |     let portSize = lookupCfg(cfgdata, configKeys.PINS_PORT_SIZE)
 947 |     let numentries = cfgdata.length >> 1
 948 |     let lines = []
 949 |     for (let i = 0; i < numentries; ++i) {
 950 |         lines.push(showKV(cfgdata[i * 2], cfgdata[i * 2 + 1], portSize, cfgdata))
 951 |     }
 952 |     lines.sort(cmpKeys)
 953 |     return lines.length ? lines.join("\n") : "Empty config."
 954 | }
 955 | 
 956 | function parsePinName(v, portSize) {
 957 |     let thePort = -1
 958 |     let pin = -1
 959 | 
 960 |     v = v.trim()
 961 | 
 962 |     v = v.replace(/^DAL\./, "")
 963 | 
 964 |     const env = enums["."][v]
 965 |     if (env !== undefined)
 966 |         return env
 967 | 
 968 |     let m = /(.*)([\|+])(.*)/.exec(v)
 969 |     if (m) {
 970 |         let v0 = parsePinName(m[1], portSize)
 971 |         let v1 = parsePinName(m[3], portSize)
 972 |         if (v0 === undefined || v1 === undefined)
 973 |             return undefined
 974 |         v0 = parseInt(v0)
 975 |         v1 = parseInt(v1)
 976 |         return "" + (m[2] == "|" ? v0 | v1 : v0 + v1)
 977 |     }
 978 | 
 979 |     m = /^P([A-Z])_?(\d+)$/.exec(v)
 980 |     if (m) {
 981 |         pin = parseInt(m[2])
 982 |         thePort = m[1].charCodeAt(0) - 65
 983 |     }
 984 | 
 985 |     m = /^P(\d+)_(\d+)$/.exec(v)
 986 |     if (m) {
 987 |         pin = parseInt(m[2])
 988 |         thePort = parseInt(m[1])
 989 |     }
 990 | 
 991 |     if (thePort >= 0) {
 992 |         if (!portSize) err("PINS_PORT_SIZE not specified, while trying to parse PIN " + v)
 993 |         if (pin >= portSize) err("Pin name invalid: " + v)
 994 |         return (thePort * portSize + pin) + ""
 995 |     }
 996 | 
 997 |     m = /^P_?(\d+)$/.exec(v)
 998 |     if (m)
 999 |         return m[1]
1000 | 
1001 |     return undefined
1002 | }
1003 | 
1004 | function patchConfig(buf, cfg) {
1005 |     init()
1006 |     const cfgMap = {}
1007 |     let lineNo = 0
1008 |     for (let line of cfg.split(/\n/)) {
1009 |         lineNo++
1010 |         line = line.replace(/(#|\/\/).*/, "")
1011 |         line = line.trim()
1012 |         if (!line)
1013 |             continue
1014 |         let m = /(\w+)\s*=\s*([^#]+)/.exec(line)
1015 |         if (!m)
1016 |             err("syntax error at config line " + lineNo)
1017 |         let kn = m[1].toUpperCase()
1018 |         let k = configKeys[kn]
1019 |         if (!k && /^_\d+$/.test(kn))
1020 |             k = parseInt(kn.slice(1))
1021 |         if (!k)
1022 |             err("Unrecognized key name: " + kn)
1023 |         cfgMap[k + ""] = m[2]
1024 |     }
1025 | 
1026 |     let cfgdata = readWriteConfig(buf, null)
1027 | 
1028 |     for (let i = 0; i < cfgdata.length; i += 2) {
1029 |         let k = cfgdata[i] + ""
1030 |         if (!cfgMap.hasOwnProperty(k))
1031 |             cfgMap[k] = cfgdata[i + 1] + ""
1032 |     }
1033 | 
1034 |     const forAll = f => {
1035 |         for (let k of Object.keys(cfgMap)) {
1036 |             let kn = configInvKeys[k]
1037 |             f(kn, k, cfgMap[k])
1038 |         }
1039 |     }
1040 | 
1041 |     // expand enums
1042 |     forAll((kn, k, v) => {
1043 |         let e = enums[kn]
1044 |         if (e && e[v.toUpperCase()])
1045 |             cfgMap[k] = e[v] + ""
1046 |     })
1047 | 
1048 |     let portSize = cfgMap[configKeys.PINS_PORT_SIZE]
1049 |     if (portSize) portSize = parseInt(portSize)
1050 |     let portSize0 = portSize
1051 |     if (portSize)
1052 |         portSize &= 0xfff;
1053 | 
1054 |     // expand pin names
1055 |     forAll((kn, k, v) => {
1056 |         let p = parsePinName(v, portSize)
1057 |         if (p)
1058 |             cfgMap[k] = p
1059 |     })
1060 | 
1061 |     // expand existing keys
1062 |     for (let i = 0; i < 10; ++i)
1063 |         forAll((kn, k, v) => {
1064 |             if (configKeys[v]) {
1065 |                 let curr = cfgMap[configKeys[v] + ""]
1066 |                 if (curr == null)
1067 |                     err("Value not specified, but referenced: " + v)
1068 |                 cfgMap[k] = curr
1069 |             }
1070 |         })
1071 | 
1072 |     let changes = ""
1073 |     forAll((kn, k, v) => {
1074 |         v = v.toUpperCase()
1075 |         if (v == "NULL" || v == "UNDEFINED") {
1076 |             let old = lookupCfg(cfgdata, k)
1077 |             changes += "remove " + showKV(k, old, portSize0) + "\n"
1078 |             delete cfgMap[k]
1079 |         }
1080 |     })
1081 | 
1082 |     forAll((kn, k, v) => {
1083 |         if (isNaN(parseInt(v)))
1084 |             err("Value not understood: " + v)
1085 |     })
1086 | 
1087 |     let sorted = Object.keys(cfgMap)
1088 |     sorted.sort((a, b) => parseInt(a) - parseInt(b))
1089 |     let patch = []
1090 |     for (let k of sorted) {
1091 |         patch.push(parseInt(k))
1092 |         patch.push(parseInt(cfgMap[k]))
1093 |     }
1094 | 
1095 |     for (let i = 0; i < patch.length; i += 2) {
1096 |         let k = patch[i]
1097 |         let v = patch[i + 1]
1098 |         let old = lookupCfg(cfgdata, k)
1099 |         if (old != v) {
1100 |             let newOne = showKV(k, v, portSize0)
1101 |             if (old !== null) {
1102 |                 let oldOne = showKV(k, old, portSize0)
1103 |                 newOne += " (was: " + oldOne.replace(/.* = /, "") + ")"
1104 |             }
1105 |             changes += newOne + "\n"
1106 |         }
1107 |     }
1108 | 
1109 |     let patched = readWriteConfig(buf, patch)
1110 | 
1111 |     return {
1112 |         changes,
1113 |         patched
1114 |     }
1115 | }
1116 | 
1117 | function parseHFile(hFile) {
1118 |     if (!hFile) return
1119 |     for (let line of hFile.split(/\n/)) {
1120 |         line = line.trim()
1121 |         let m = /#define\s+CFG_(\w+)\s+(\d+)/.exec(line)
1122 |         if (m) {
1123 |             let k = m[1]
1124 |             let v = parseInt(m[2])
1125 |             configKeys[k] = parseInt(v)
1126 |             configInvKeys[v + ""] = k
1127 |             console.log(`  ${k}: ${v},`)
1128 |         }
1129 |     }
1130 | }
1131 | 
1132 | function init() {
1133 |     for (let k of Object.keys(configKeys)) {
1134 |         let v = configKeys[k]
1135 |         configInvKeys[v + ""] = k
1136 |     }
1137 | }
1138 | 
1139 | function main() {
1140 |     let uf2 = readBin(process.argv[2])
1141 | 
1142 |     if (process.argv[3]) {
1143 |         let cfg = readBin(process.argv[3]).toString("utf8")
1144 |         let r = patchConfig(uf2, cfg)
1145 |         if (!r.changes)
1146 |             console.log("No changes.")
1147 |         else
1148 |             console.log("\nChanges:\n" + r.changes)
1149 |         console.log("# Writing config...")
1150 |         fs.writeFileSync(process.argv[2], r.patched)
1151 |     } else {
1152 |         console.log(readConfig(uf2))
1153 |     }
1154 | }
1155 | 
1156 | 
1157 | if (typeof window == "undefined")
1158 |     main()


--------------------------------------------------------------------------------