kmwebnet/OpenSK
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

New documentation for develop (#408)

Browse Source 
* documentation refactoring

* documentation fixes

* distilled instructions for MDK

* remove deploy TODO after creating PR

* fixes typos
This commit is contained in:
kaczmarczyck
2021-11-18 16:57:58 +01:00
committed by GitHub
parent 40e912f8ac
commit ae4e32ba4a
9 changed files with 545 additions and 440 deletions
Download Patch File Download Diff File Expand all files Collapse all files

85
docs/boards/nrf52840_dongle.md Normal file
View File

@@ -0,0 +1,85 @@
# <img alt="OpenSK logo" src="../img/OpenSK.svg" width="200px">
## Nordic nRF52840 Dongle
![Nordic dongle](../img/dongle_front.jpg)
### 3D printed enclosure
To protect and carry your key, we partnered with a professional designer and we
are providing a custom enclosure that can be printed on both professional 3D
printers and hobbyist models.
![OpenSK Enclosure](img/enclosure.jpg)
All the required files can be downloaded from
[Thingiverse](https://www.thingiverse.com/thing:4132768) including the STEP
file, allowing you to easily make the modifications you need to further
customize it.
### Flashing using DFU (preferred method)
To flash the firmware, run:
```shell
./deploy.py --board=nrf52840_dongle_dfu --opensk --programmer=nordicdfu
```
The script will ask you to switch to DFU mode. To activate that on your dongle,
keep the button pressed while inserting the device into your USB port. You may
additionally need to press the tiny, sideways facing reset button. The device
indicates DFU mode with a slowly blinking red LED.
### Flashing with an external programmer (JLink, OpenOCD, etc.)
If you want to use JTAG with the dongle, you need additional hardware.
* a [Segger J-Link](https://www.segger.com/products/debug-probes/j-link/) JTAG
probe.
* a
[TC2050 Tag-Connect programming cable](https://www.tag-connect.com/product/tc2050-idc-nl-10-pin-no-legs-cable-with-ribbon-connector).
* a [Tag-Connect TC2050 ARM2010](http://www.tag-connect.com/TC2050-ARM2010)
adaptor
* optionally a
[Tag-Connect TC2050 retainer clip](http://www.tag-connect.com/TC2050-CLIP)
to keep the spring loaded connector pressed to the PCB.
Follow these steps:
1. The JTAG probe used for programming won't provide power to the board.
Therefore you will need to use a USB-A extension cable to power the dongle
through its USB port.
1. Connect the TC2050 cable to the pads below the PCB:
![Nordic dongle pads](../img/dongle_pads.jpg)
1. You can use the retainer clip if you have one to avoid maintaining pressure
between the board and the cable:
![Nordic dongle retainer clip](../img/dongle_clip.jpg)
1. Depending on the programmer you're using, you may have to adapt the next
command line. Run our script for compiling/flashing Tock OS on your device:
```shell
$ ./deploy.py --board=nrf52840_dongle_opensk --programmer=jlink
```
1. Remove the programming cable and the USB-A extension cable.
### Buttons and LEDs
The bigger, white button conveys user presence to the application. Some actions
like register and login will make the dongle blink, asking you to confirm the
transaction with a button press. The small, sideways pointing buttong next to it
restarts the dongle.
The 2 LEDs show the state of the app. There are different patterns:
| Pattern | Cause |
|------------------------------------|------------------------|
| all LEDs and colors | app panic |
| green and blue blinking | asking for touch |
| all LEDs and colors for 5s | wink (just saying Hi!) |
| red slow blink | DFU mode |

23
docs/boards/nrf52840_feitian.md Normal file
View File

@@ -0,0 +1,23 @@
# <img alt="OpenSK logo" src="../img/OpenSK.svg" width="200px">
## Feitian OpenSK USB Dongle
### Flashing using DFU
This board is similar in hardware to the Nordic nRF52840 Dongle. You can use DFU
to flash it, instructions to enter DFU mode depend on the version of your
hardware. See
[Feitian's instructions](https://feitiantech.github.io/OpenSK_USB/). In short:
* In V1, use a paperclip to press the Reset button through the tiny hole.
* In V2, push and hold the user button for more than 10 seconds after
connecting your device.
Afterwards, you can flash your Feitian OpenSK using DFU following the
[instructions for the Nordic nRF52840 Dongle](nrf52840_dongle.md#Flashing-using-DFU).
### Buttons and LEDs
For both hardware versions, the buttons and LEDs are described in detail in the
[hardware section](https://feitiantech.github.io/OpenSK_USB/hardware/) of
Feitian's website.

47
docs/boards/nrf52840_mdk.md Normal file
View File

@@ -0,0 +1,47 @@
# <img alt="OpenSK logo" src="../img/OpenSK.svg" width="200px">
## Nordic nRF52840 MDK
Makerdiary has instructions on their [website](https://wiki.makerdiary.com/nrf52840-mdk-usb-dongle/opensk/). They use a custom script to deploy via DFU.
After general setup, you still need these steps:
1. Create the hexfile with the firmware.
```shell
./deploy.py --board=nrf52840_mdk_dfu --opensk --programmer=none
```
1. Download the
[script](https://github.com/makerdiary/nrf52840-mdk-usb-dongle/blob/master/tools/uf2conv.py)
from Makerdiary's GitHub into the OpenSK repository.
1. Run the script:
```shell
python3 uf2conv.py -c -f 0xada52840 -o target/opensk.uf2 target/nrf52840_mdk_dfu_merged.hex
```
1. Boot into DFU mode. Keep the user button pressed on your hardware while
inserting it into a USB slot. You should see a bit of red blinking, and then
a constant green light.
1. Your dongle should appear in your normal file browser like other USB sticks.
Copy the file `target/opensk.uf2` over.
1. Replug to reboot.
### Buttons and LEDs
The big, white button conveys user presence to the application. Some actions
like register and login will make the device blink, asking you to confirm the
transaction with a button press.
The LED shows the state of the app. There are different patterns:
| Pattern | Cause |
|------------------------------------|------------------------|
| red glow | busy |
| red and blue blinking | asking for touch |
| red, green, white pattern for 5s | wink (just saying Hi!) |
| constant green | DFU mode |

50
docs/boards/nrf52840dk.md Normal file
View File

@@ -0,0 +1,50 @@
# <img alt="OpenSK logo" src="../img/OpenSK.svg" width="200px">
## Nordic nRF52840-DK board
![Nordic development kit](../img/devkit_annotated.jpg)
### Flashing using JTAG
The development board comes with its own JTAG port, so the default programmer
is the easiest and most convenient. You can flash OpenSK with these steps:
1. Connect a micro USB cable to the JTAG USB port.
1. Run our script for compiling/flashing Tock OS and OpenSK on your device:
```shell
./deploy.py --board=nrf52840dk_opensk --opensk
```
1. Connect a micro USB cable to the device USB port.
**Note**: Due to current limitations of our implementation and Tock, you may
have to press the `BOOT/RESET` button, located next to the device USB port on
the board in order to see your OpenSK device on your system.
### Buttons and LEDs
Out of the 5 buttons, the group of 4 behaves identically. They all convey user
presence to the application. Some actions like register and login will make the
board blink, asking you to confirm the transaction with a button press. The
remaining fifth button restarts the board.
The group of 4 LEDs on the right show the state of the app. There are different
patterns:
| Pattern | Cause |
|------------------------------------|------------------------|
| LED1 slow blink | kernel panic |
| all LEDs blinking together | app panic |
| LED1+4 and LED2+3 fast alternating | asking for touch |
| fast swirling | wink (just saying Hi!) |
| circle | allocator panic |
The LEDs closer to the JTAG port indicates the power and debugging state.
There are 3 switches that need to be in the correct position:
* Power (bottom left): On
* nRF power source (center left): VDD
* SW6 (top right): DEFAULT