shimun/solo
1
0
Fork 0
Code Issues Pull Requests Releases 1 Wiki Activity

Merge pull request #236 from Wesseldr/patch-3

Browse Source 
Cleaned nucleo32-board.md
This commit is contained in:
Nicolas Stalder 2019-08-06 13:48:00 +02:00 committed by GitHub
commit 4e3420f19f
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 115 additions and 78 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

137
docs/solo/nucleo32-board.md
View File

@ -1,13 +1,14 @@
# Nucleo32 board preparation # Nucleo32 board preparation
Additional steps are required to run the firmware on the Nucleo32 board. Additional steps are required to run the firmware on the Nucleo32 board.
## USB-A cable ## USB-A cable
Board does not provide an USB cable / socket for the target MCU communication. 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: Own provided USB plug has to be connected in the following way:
| PIN / Arduino PIN | MCU leg | USB wire color | Signal | | PIN / Arduino PIN | MCU leg | USB wire color | Signal |
|---|---|---|---| | ----------------- | ------- | -------------- | ------ |
| D10 / PA11 | 21 | white | D- | | D10 / PA11 | 21 | white | D- |
| D2 / PA12 | 22 | green | D+ | | D2 / PA12 | 22 | green | D+ |
| GND (near D2) | ------- | black | GND | | GND (near D2) | ------- | black | GND |
@ -17,7 +18,7 @@ Each USB plug pin should be connected via the wire in a color defined by the sta
multimeter for additional safety. USB plug description: multimeter for additional safety. USB plug description:
| PIN | USB wire color | Signal | | PIN | USB wire color | Signal |
|---|---|---| | --- | -------------- | ------ |
| 4 | black | GND | | 4 | black | GND |
| 3 | green | D+ | | 3 | green | D+ |
| 2 | white | D- | | 2 | white | D- |
@ -27,17 +28,15 @@ 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]. 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). 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. Make sure 5V is not connected, and is covered from contacting with the board elements.
Based on [USB-A_schematic.pdf]. Based on [USB-A_schematic.pdf].
## Firmware modification ## Firmware modification
Following patch has to be applied to skip the user presence confirmation, for tests. Might be applied at a later stage. Following patch has to be applied to skip the user presence confirmation, for tests. Might be applied at a later stage.
```text ```text
diff --git a/targets/stm32l432/src/app.h b/targets/stm32l432/src/app.h diff --git a/targets/stm32l432/src/app.h b/targets/stm32l432/src/app.h
index c14a7ed..c89c3b5 100644 index c14a7ed..c89c3b5 100644
@ -52,47 +51,54 @@ index c14a7ed..c89c3b5 100644
#endif #endif
``` ```
It is possible to provide a button and connect it to the MCU pins, as instructed in [USB-A_schematic.pdf]:
It is possible to provide a button and connect it to the MCU pins, as instructed in [USB-A_schematic.pdf]:
```text ```text
PA0 / pin 6 --> button --> GND PA0 / pin 6 --> button --> GND
``` ```
In that case the mentioned patch would not be required. 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 Environment: Fedora 29 x64, Linux 4.19.9
See https://docs.solokeys.io/solo/building/ for the original guide. Here details not included there will be covered. See <https://docs.solokeys.io/solo/building/> 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]. 1. Download current [ARM tools] package: [gcc-arm-none-eabi-8-2018-q4-major-linux.tar.bz2].
2. Extract the archive. 2. Extract the archive.
3. Add full path to the `./bin` directory as first entry to the `$PATH` variable, 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`. 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 ### Install flashing software
[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: 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. go to bottom page and from STM32CubeProg row select Download button.
2. Unzip contents of the archive. 2\. Unzip contents of the archive.
3. Run *Linux setup 3\. Run \*Linux setup
4. In installation directory go to ./bin - there the ./STM32_Programmer_CLI is located 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. 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: If you're on OsX and installed the STM32CubeProg, you need to add the following to your path:
```bash ```bash
# ~/.bash_profile # ~/.bash_profile
export PATH="/Applications/STMicroelectronics/STM32Cube/STM32CubeProgrammer/STM32CubeProgrammer.app/Contents/MacOs/bin/":$PATH export PATH="/Applications/STMicroelectronics/STM32Cube/STM32CubeProgrammer/STM32CubeProgrammer.app/Contents/MacOs/bin/":$PATH
``` ```
# Building and flashing ## Building and flashing
## Building
Please follow https://docs.solokeys.io/solo/building/, as the build way changes rapidly. ### Building
Please follow <https://docs.solokeys.io/solo/building/>, as the build way changes rapidly.
Currently (8.1.19) to build the firmware, following lines should be executed Currently (8.1.19) to build the firmware, following lines should be executed
```bash ```bash
# while in the main project directory # while in the main project directory
cd targets/stm32l432 cd targets/stm32l432
@ -103,7 +109,8 @@ make build-hacker DEBUG=1
Note: `DEBUG=2` stops the device initialization, until a serial client will be attached to its virtual port. 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. Do not use it, if you do not plan to do so.
## Flashing via the Makefile command ### Flashing via the Makefile command
```bash ```bash
# while in the main project directory # while in the main project directory
# create Python virtual environment with required packages, and activate # create Python virtual environment with required packages, and activate
@ -119,20 +126,27 @@ make flash
# STM32_Programmer_CLI -c port=SWD -halt -d all.hex -rst # 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: In case you already have a firmware to flash (named `all.hex`), please run the following:
```bash ```bash
STM32_Programmer_CLI -c port=SWD -halt -e all --readunprotect STM32_Programmer_CLI -c port=SWD -halt -e all --readunprotect
STM32_Programmer_CLI -c port=SWD -halt -d all.hex -rst STM32_Programmer_CLI -c port=SWD -halt -d all.hex -rst
``` ```
# Testing ## Testing
### Internal
## Internal
Project-provided tests. Project-provided tests.
### Simulated device
#### Simulated device
A simulated device is provided to test the HID layer. A simulated device is provided to test the HID layer.
#### Build
##### Build
```bash ```bash
make clean make clean
cd tinycbor cd tinycbor
@ -141,7 +155,8 @@ cd ..
make env2 make env2
``` ```
#### Execution ##### Execution
```bash ```bash
# run simulated device (will create a network UDP server) # run simulated device (will create a network UDP server)
./main ./main
@ -151,64 +166,86 @@ make env2
./env2/bin/python python-fido2/examples/credential.py ./env2/bin/python python-fido2/examples/credential.py
``` ```
### Real device #### Real device
```bash ```bash
# while in the main project directory # while in the main project directory
# not passing as of 8.1.19, due to test solution issues # not passing as of 8.1.19, due to test solution issues
make fido2-test make fido2-test
``` ```
## External ### External
### FIDO2 test sites #### FIDO2 test sites
1. https://webauthn.bin.coffee/
2. https://github.com/apowers313/fido2-server-demo/
3. https://webauthn.org/
### U2F test sites 1. <https://webauthn.bin.coffee/>
1. https://u2f.bin.coffee/ 2. <https://github.com/apowers313/fido2-server-demo/>
2. https://demo.yubico.com/u2f 3. <https://webauthn.org/>
### FIDO2 standalone clients #### U2F test sites
1. https://github.com/Nitrokey/u2f-ref-code
2. https://github.com/Yubico/libfido2
3. https://github.com/Yubico/python-fido2
4. https://github.com/google/pyu2f
1. <https://u2f.bin.coffee/>
2. <https://demo.yubico.com/u2f>
#### FIDO2 standalone clients
1. <https://github.com/Nitrokey/u2f-ref-code>
2. <https://github.com/Yubico/libfido2>
3. <https://github.com/Yubico/python-fido2>
4. <https://github.com/google/pyu2f>
## 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, Device opens an USB-emulated serial port to output its messages. While Nucleo board offers such already,
the Solo device provides its own. the Solo device provides its own.
- Provided Python tool - Provided Python tool
```bash ```bash
python3 ../../tools/solotool.py monitor /dev/solokey-serial python3 ../../tools/solotool.py monitor /dev/solokey-serial
``` ```
- External application - External application
```bash ```bash
sudo picocom -b 115200 /dev/solokey-serial sudo picocom -b 115200 /dev/solokey-serial
``` ```
where `/dev/solokey-serial` is an udev symlink to `/dev/ttyACM1`. where `/dev/solokey-serial` is an udev symlink to `/dev/ttyACM1`.
# Other ## Other
## Dumping firmware ### Dumping firmware
Size is calculated using bash arithmetic. Size is calculated using bash arithmetic.
```bash ```bash
STM32_Programmer_CLI -c port=SWD -halt -u 0x0 $((256*1024)) current.hex STM32_Programmer_CLI -c port=SWD -halt -u 0x0 $((256*1024)) current.hex
``` ```
## Software reset ### Software reset
```bash ```bash
STM32_Programmer_CLI -c port=SWD -rst 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 Client script requires some Python packages, which could be easily installed locally to the project
via the Makefile command. It is sufficient to run: via the Makefile command. It is sufficient to run:
```bash ```bash
make env3 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
[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