From a8c7c43e14d3efb06e601c8ea856391a866adcc6 Mon Sep 17 00:00:00 2001 From: Wessel dR Date: Tue, 6 Aug 2019 12:40:05 +0200 Subject: [PATCH 1/3] Cleaned nucleo32-board.md The original pull request #65 was not completely compliant. hopefully this one is. --- docs/solo/nucleo32-board.md | 249 ++++++++++++++++++++++++++++++++++++ 1 file changed, 249 insertions(+) create mode 100644 docs/solo/nucleo32-board.md diff --git a/docs/solo/nucleo32-board.md b/docs/solo/nucleo32-board.md new file mode 100644 index 0000000..7ca6202 --- /dev/null +++ b/docs/solo/nucleo32-board.md @@ -0,0 +1,249 @@ +# Nucleo32 board preparation + +Additional steps are required to run the firmware on the Nucleo32 board. + +## USB-A cable + +Board does not provide an USB cable / socket for the target MCU communication. +Own provided USB plug has to be connected in the following way: + +| PIN / Arduino PIN | MCU leg | USB wire color | Signal | +| ----------------- | ------- | -------------- | ------ | +| D10 / PA11 | 21 | white | D- | +| D2 / PA12 | 22 | green | D+ | +| GND (near D2) | ------- | black | GND | +| **not connected** | ------- | red | 5V | + +Each USB plug pin should be connected via the wire in a color defined by the standard. It might be confirmed with a +multimeter for additional safety. USB plug description: + +| PIN | USB wire color | Signal | +| --- | -------------- | ------ | +| 4 | black | GND | +| 3 | green | D+ | +| 2 | white | D- | +| 1 | red | 5V | + +See this [USB plug] image, and Wikipedia's [USB plug description]. + +Plug in [USB-A_schematic.pdf] has wrong wire order, registered as [solo-hw#1]. + +[solo-hw#1]: https://github.com/solokeys/solo-hw/issues/1 + +[usb plug]: https://upload.wikimedia.org/wikipedia/commons/thumb/6/67/USB.svg/1200px-USB.svg.png + +[usb plug description]: https://en.wikipedia.org/wiki/USB#Receptacle_(socket)_identification + +The power is taken from the debugger / board (unless the board is configured in another way). +Make sure 5V is not connected, and is covered from contacting with the board elements. + +Based on [USB-A_schematic.pdf]. + +## Firmware modification + +Following patch has to be applied to skip the user presence confirmation, for tests. Might be applied at a later stage. + +```text +diff --git a/targets/stm32l432/src/app.h b/targets/stm32l432/src/app.h +index c14a7ed..c89c3b5 100644 +--- a/targets/stm32l432/src/app.h ++++ b/targets/stm32l432/src/app.h +@@ -71,6 +71,6 @@ void hw_init(void); + #define SOLO_BUTTON_PIN LL_GPIO_PIN_0 + + #define SKIP_BUTTON_CHECK_WITH_DELAY 0 +-#define SKIP_BUTTON_CHECK_FAST 0 ++#define SKIP_BUTTON_CHECK_FAST 1 + + #endif +``` + +It is possible to provide a button and connect it to the MCU pins, as instructed in [USB-A_schematic.pdf]: + +```text +PA0 / pin 6 --> button --> GND +``` + +In that case the mentioned patch would not be required. + +[usb-a_schematic.pdf]: https://github.com/solokeys/solo-hw/releases/download/1.2/USB-A_schematic.pdf + +# Development environment setup + +Environment: Fedora 29 x64, Linux 4.19.9 + +See for the original guide. Here details not included there will be covered. + +## Install ARM tools + +1. Download current [ARM tools] package: [gcc-arm-none-eabi-8-2018-q4-major-linux.tar.bz2]. +2. Extract the archive. +3. Add full path to the `./bin` directory as first entry to the `$PATH` variable, + as in `~/gcc-arm/gcc-arm-none-eabi-8-2018-q4-major/bin/:$PATH`. + +[arm tools]: https://developer.arm.com/open-source/gnu-toolchain/gnu-rm/downloads + +[gcc-arm-none-eabi-8-2018-q4-major-linux.tar.bz2]: https://developer.arm.com/-/media/Files/downloads/gnu-rm/8-2018q4/gcc-arm-none-eabi-8-2018-q4-major-linux.tar.bz2?revision=d830f9dd-cd4f-406d-8672-cca9210dd220?product=GNU%20Arm%20Embedded%20Toolchain,64-bit,,Linux,8-2018-q4-major + +## Install flashing software + +ST provides a CLI flashing tool - `STM32_Programmer_CLI`. It can be downloaded directly from the vendor's site: +1\. Go to [download site URL](https://www.st.com/content/st_com/en/products/development-tools/software-development-tools/stm32-software-development-tools/stm32-programmers/stm32cubeprog.html), +go to bottom page and from STM32CubeProg row select Download button. +2\. Unzip contents of the archive. +3\. Run \*Linux setup +4\. In installation directory go to ./bin - there the ./STM32_Programmer_CLI is located +5\. Add symlink to the STM32 CLI binary to .local/bin. Make sure the latter it is in $PATH. + +If you're on OsX and installed the STM32CubeProg, you need to add the following to your path: + +```bash +# ~/.bash_profile +export PATH="/Applications/STMicroelectronics/STM32Cube/STM32CubeProgrammer/STM32CubeProgrammer.app/Contents/MacOs/bin/":$PATH +``` + +# Building and flashing + +## Building + +Please follow , as the build way changes rapidly. +Currently (8.1.19) to build the firmware, following lines should be executed + +```bash +# while in the main project directory +cd targets/stm32l432 +make cbor +make build-hacker DEBUG=1 +``` + +Note: `DEBUG=2` stops the device initialization, until a serial client will be attached to its virtual port. +Do not use it, if you do not plan to do so. + +## Flashing via the Makefile command + +```bash +# while in the main project directory +# create Python virtual environment with required packages, and activate +make env3 +. env3/bin/activate +# Run flashing +cd ./targets/stm32l432 +make flash + # which runs: + # flash: solo.hex bootloader.hex + # python merge_hex.py solo.hex bootloader.hex all.hex (intelhex library required) + # STM32_Programmer_CLI -c port=SWD -halt -e all --readunprotect + # STM32_Programmer_CLI -c port=SWD -halt -d all.hex -rst +``` + +## Manual flashing + +In case you already have a firmware to flash (named `all.hex`), please run the following: + +```bash +STM32_Programmer_CLI -c port=SWD -halt -e all --readunprotect +STM32_Programmer_CLI -c port=SWD -halt -d all.hex -rst +``` + +# Testing + +## Internal + +Project-provided tests. + +### Simulated device + +A simulated device is provided to test the HID layer. + +#### Build + +```bash +make clean +cd tinycbor +make +cd .. +make env2 +``` + +#### Execution + +```bash +# run simulated device (will create a network UDP server) +./main +# run test 1 +./env2/bin/python tools/ctap_test.py +# run test 2 (or other files in the examples directory) +./env2/bin/python python-fido2/examples/credential.py +``` + +### Real device + +```bash +# while in the main project directory +# not passing as of 8.1.19, due to test solution issues +make fido2-test +``` + +## External + +### FIDO2 test sites + +1. +2. +3. + +### U2F test sites + +1. +2. + +### FIDO2 standalone clients + +1. +2. +3. +4. + +# USB serial console reading + +Device opens an USB-emulated serial port to output its messages. While Nucleo board offers such already, +the Solo device provides its own. + +- Provided Python tool + +```bash +python3 ../../tools/solotool.py monitor /dev/solokey-serial +``` + +- External application + +```bash +sudo picocom -b 115200 /dev/solokey-serial +``` + +where `/dev/solokey-serial` is an udev symlink to `/dev/ttyACM1`. + +# Other + +## Dumping firmware + +Size is calculated using bash arithmetic. + +```bash +STM32_Programmer_CLI -c port=SWD -halt -u 0x0 $((256*1024)) current.hex +``` + +## Software reset + +```bash +STM32_Programmer_CLI -c port=SWD -rst +``` + +## Installing required Python packages + +Client script requires some Python packages, which could be easily installed locally to the project +via the Makefile command. It is sufficient to run: + +```bash +make env3 +``` From 29b2032dae7edf0fb2ae297bd3eda1bc19ef772a Mon Sep 17 00:00:00 2001 From: Wessel de Roode Date: Tue, 6 Aug 2019 13:06:06 +0200 Subject: [PATCH 2/3] fixing final-definitions and misc --- docs/solo/nucleo32-board.md | 70 ++++++++++++++++++------------------- 1 file changed, 35 insertions(+), 35 deletions(-) diff --git a/docs/solo/nucleo32-board.md b/docs/solo/nucleo32-board.md index 7ca6202..008839d 100644 --- a/docs/solo/nucleo32-board.md +++ b/docs/solo/nucleo32-board.md @@ -28,12 +28,6 @@ See this [USB plug] image, and Wikipedia's [USB plug description]. Plug in [USB-A_schematic.pdf] has wrong wire order, registered as [solo-hw#1]. -[solo-hw#1]: https://github.com/solokeys/solo-hw/issues/1 - -[usb plug]: https://upload.wikimedia.org/wikipedia/commons/thumb/6/67/USB.svg/1200px-USB.svg.png - -[usb plug description]: https://en.wikipedia.org/wiki/USB#Receptacle_(socket)_identification - The power is taken from the debugger / board (unless the board is configured in another way). Make sure 5V is not connected, and is covered from contacting with the board elements. @@ -66,15 +60,13 @@ PA0 / pin 6 --> button --> GND In that case the mentioned patch would not be required. -[usb-a_schematic.pdf]: https://github.com/solokeys/solo-hw/releases/download/1.2/USB-A_schematic.pdf - -# Development environment setup +## Development environment setup Environment: Fedora 29 x64, Linux 4.19.9 See for the original guide. Here details not included there will be covered. -## Install ARM tools +### Install ARM tools 1. Download current [ARM tools] package: [gcc-arm-none-eabi-8-2018-q4-major-linux.tar.bz2]. 2. Extract the archive. @@ -85,15 +77,15 @@ See for the original guide. Here detai [gcc-arm-none-eabi-8-2018-q4-major-linux.tar.bz2]: https://developer.arm.com/-/media/Files/downloads/gnu-rm/8-2018q4/gcc-arm-none-eabi-8-2018-q4-major-linux.tar.bz2?revision=d830f9dd-cd4f-406d-8672-cca9210dd220?product=GNU%20Arm%20Embedded%20Toolchain,64-bit,,Linux,8-2018-q4-major -## Install flashing software +### Install flashing software ST provides a CLI flashing tool - `STM32_Programmer_CLI`. It can be downloaded directly from the vendor's site: -1\. Go to [download site URL](https://www.st.com/content/st_com/en/products/development-tools/software-development-tools/stm32-software-development-tools/stm32-programmers/stm32cubeprog.html), +1. Go to [download site URL](https://www.st.com/content/st_com/en/products/development-tools/software-development-tools/stm32-software-development-tools/stm32-programmers/stm32cubeprog.html), go to bottom page and from STM32CubeProg row select Download button. -2\. Unzip contents of the archive. -3\. Run \*Linux setup -4\. In installation directory go to ./bin - there the ./STM32_Programmer_CLI is located -5\. Add symlink to the STM32 CLI binary to .local/bin. Make sure the latter it is in $PATH. +2. Unzip contents of the archive. +3. Run \*Linux setup +4. In installation directory go to ./bin - there the ./STM32_Programmer_CLI is located +5. Add symlink to the STM32 CLI binary to .local/bin. Make sure the latter it is in $PATH. If you're on OsX and installed the STM32CubeProg, you need to add the following to your path: @@ -102,9 +94,9 @@ If you're on OsX and installed the STM32CubeProg, you need to add the following export PATH="/Applications/STMicroelectronics/STM32Cube/STM32CubeProgrammer/STM32CubeProgrammer.app/Contents/MacOs/bin/":$PATH ``` -# Building and flashing +## Building and flashing -## Building +### Building Please follow , as the build way changes rapidly. Currently (8.1.19) to build the firmware, following lines should be executed @@ -119,7 +111,7 @@ make build-hacker DEBUG=1 Note: `DEBUG=2` stops the device initialization, until a serial client will be attached to its virtual port. Do not use it, if you do not plan to do so. -## Flashing via the Makefile command +### Flashing via the Makefile command ```bash # while in the main project directory @@ -136,7 +128,7 @@ make flash # STM32_Programmer_CLI -c port=SWD -halt -d all.hex -rst ``` -## Manual flashing +### Manual flashing In case you already have a firmware to flash (named `all.hex`), please run the following: @@ -145,17 +137,17 @@ STM32_Programmer_CLI -c port=SWD -halt -e all --readunprotect STM32_Programmer_CLI -c port=SWD -halt -d all.hex -rst ``` -# Testing +## Testing -## Internal +### Internal Project-provided tests. -### Simulated device +#### Simulated device A simulated device is provided to test the HID layer. -#### Build +##### Build ```bash make clean @@ -165,7 +157,7 @@ cd .. make env2 ``` -#### Execution +##### Execution ```bash # run simulated device (will create a network UDP server) @@ -176,7 +168,7 @@ make env2 ./env2/bin/python python-fido2/examples/credential.py ``` -### Real device +#### Real device ```bash # while in the main project directory @@ -184,27 +176,27 @@ make env2 make fido2-test ``` -## External +### External -### FIDO2 test sites +#### FIDO2 test sites 1. 2. 3. -### U2F test sites +#### U2F test sites 1. 2. -### FIDO2 standalone clients +#### FIDO2 standalone clients 1. 2. 3. 4. -# USB serial console reading +## USB serial console reading Device opens an USB-emulated serial port to output its messages. While Nucleo board offers such already, the Solo device provides its own. @@ -223,9 +215,9 @@ sudo picocom -b 115200 /dev/solokey-serial where `/dev/solokey-serial` is an udev symlink to `/dev/ttyACM1`. -# Other +## Other -## Dumping firmware +### Dumping firmware Size is calculated using bash arithmetic. @@ -233,13 +225,13 @@ Size is calculated using bash arithmetic. STM32_Programmer_CLI -c port=SWD -halt -u 0x0 $((256*1024)) current.hex ``` -## Software reset +### Software reset ```bash STM32_Programmer_CLI -c port=SWD -rst ``` -## Installing required Python packages +### Installing required Python packages Client script requires some Python packages, which could be easily installed locally to the project via the Makefile command. It is sufficient to run: @@ -247,3 +239,11 @@ via the Makefile command. It is sufficient to run: ```bash make env3 ``` + +[solo-hw#1]: https://github.com/solokeys/solo-hw/issues/1 + +[usb plug]: https://upload.wikimedia.org/wikipedia/commons/thumb/6/67/USB.svg/1200px-USB.svg.png + +[usb plug description]: https://en.wikipedia.org/wiki/USB#Receptacle_(socket)_identification + +[usb-a_schematic.pdf]: https://github.com/solokeys/solo-hw/releases/download/1.2/USB-A_schematic.pdf From 6dfe42e48679c1f8463cb4b302630a1342113f03 Mon Sep 17 00:00:00 2001 From: Wessel de Roode Date: Tue, 6 Aug 2019 13:11:51 +0200 Subject: [PATCH 3/3] All cleaned up now ? --- docs/solo/nucleo32-board.md | 20 +++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-) diff --git a/docs/solo/nucleo32-board.md b/docs/solo/nucleo32-board.md index 008839d..e48312d 100644 --- a/docs/solo/nucleo32-board.md +++ b/docs/solo/nucleo32-board.md @@ -69,23 +69,21 @@ See for the original guide. Here detai ### Install ARM tools 1. Download current [ARM tools] package: [gcc-arm-none-eabi-8-2018-q4-major-linux.tar.bz2]. + 2. Extract the archive. + 3. Add full path to the `./bin` directory as first entry to the `$PATH` variable, as in `~/gcc-arm/gcc-arm-none-eabi-8-2018-q4-major/bin/:$PATH`. -[arm tools]: https://developer.arm.com/open-source/gnu-toolchain/gnu-rm/downloads - -[gcc-arm-none-eabi-8-2018-q4-major-linux.tar.bz2]: https://developer.arm.com/-/media/Files/downloads/gnu-rm/8-2018q4/gcc-arm-none-eabi-8-2018-q4-major-linux.tar.bz2?revision=d830f9dd-cd4f-406d-8672-cca9210dd220?product=GNU%20Arm%20Embedded%20Toolchain,64-bit,,Linux,8-2018-q4-major - ### Install flashing software ST provides a CLI flashing tool - `STM32_Programmer_CLI`. It can be downloaded directly from the vendor's site: -1. Go to [download site URL](https://www.st.com/content/st_com/en/products/development-tools/software-development-tools/stm32-software-development-tools/stm32-programmers/stm32cubeprog.html), +1\. Go to [download site URL](https://www.st.com/content/st_com/en/products/development-tools/software-development-tools/stm32-software-development-tools/stm32-programmers/stm32cubeprog.html), go to bottom page and from STM32CubeProg row select Download button. -2. Unzip contents of the archive. -3. Run \*Linux setup -4. In installation directory go to ./bin - there the ./STM32_Programmer_CLI is located -5. Add symlink to the STM32 CLI binary to .local/bin. Make sure the latter it is in $PATH. +2\. Unzip contents of the archive. +3\. Run \*Linux setup +4\. In installation directory go to ./bin - there the ./STM32_Programmer_CLI is located +5\. Add symlink to the STM32 CLI binary to .local/bin. Make sure the latter it is in $PATH. If you're on OsX and installed the STM32CubeProg, you need to add the following to your path: @@ -247,3 +245,7 @@ make env3 [usb plug description]: https://en.wikipedia.org/wiki/USB#Receptacle_(socket)_identification [usb-a_schematic.pdf]: https://github.com/solokeys/solo-hw/releases/download/1.2/USB-A_schematic.pdf + +[arm tools]: https://developer.arm.com/open-source/gnu-toolchain/gnu-rm/downloads + +[gcc-arm-none-eabi-8-2018-q4-major-linux.tar.bz2]: https://developer.arm.com/-/media/Files/downloads/gnu-rm/8-2018q4/gcc-arm-none-eabi-8-2018-q4-major-linux.tar.bz2?revision=d830f9dd-cd4f-406d-8672-cca9210dd220?product=GNU%20Arm%20Embedded%20Toolchain,64-bit,,Linux,8-2018-q4-major