7.1 KiB
Executable File
Tutorial: Getting started with the solo hacker
This is small guide to let you get started with the solo hacker key. In the end you will have set up everything you need and changed the LED from green to red.
Some additional ressources
This tutorial will take you through all the necessary steps needed to install and get the solo key running. Before we start, I will just list you additional ressources, which might have important information for you:
- The git repository: Here you will find all the code and a quick readme.
- The Documenation: The official documentation. Especially the build instructions are worth a look, if you got stuck.
Getting the prerequisites
There are two main tools you will need to work on your solo hacker:
- ARM Compiler tool chain
- Solo python tool
The ARM Compiler is used to compile your C-code to a hex file, which can then be deployed onto your solo hacker. The solo tool helps with deploying, updating etc. of the solo hacker. It is a python3 tool. So make sure, that you got Python3 installed on your system [pip](https://pip.pypa.io/en/stable/) might also come in handy.
Besides that, you will also need to get the solo code.
Get the code
The codebase for the solo hacker and other solo keys, can be found at this git repository. So just clone this into your development folder. Make sure, that all the submodules are loaded by using the following command. I forgot to get all the submoules at my first try and the make command failed I got an error message telling me, that no solo.elf target can be found.
git clone --recurse-submodules https://github.com/solokeys/solo
Getting the ARM Compiler tool chain
Download the Compiler tool chain for your system here. After you have downloaded it, you will have to unzip it and add the path to the installation folder.
Readme There is a readme.txt __ in gcc-arm-none-eabi-x-yyyy-dd-major/share/doc/gcc-arm-none-eabi. It contains installation guides for Linux, Windows and Mac.
Installation As I used Mac, I will guide you through the installation using MacOS. If you have unpacked the folder already, you can skip the first step.
#Unzip the tarball
cd $install_dir && tar xjf gcc-arm-none-eabi-*-yyyymmdd-mac.tar.bz2
#Set path
export PATH=$PATH:$install_dir/gcc-arm-none-eabi-*/bin
#Test if it works
arm-none-eabi-gcc
If everything worked your output should like this:
arm-none-eabi-gcc: fatal error: no input files
compilation terminated.
Getting the solo tool
There are several ways, which are listed at the build instructions. If you are familiar with pip, just use this.
pip install solo1
#Or
pip3 install solo1
Install all other requirements
To do this either do it in the virtual env or directly on your machine. The requirements can be found in the source folder in requirements.txt.
#Move to source folder
cd solo
#Install requirements, use pip3 otherwise
pip install -r solo/tools/requirements.txt
Let's get a red light blinking
You will find the code for the key in /solo/targets/stm32l432 The target might have another id for you, so just use that id. The LED colors can be found in /solo/targets/stm32l432 /src/app.h. To change the color we will just have to change the hex-value. Out of the box it should look like this:
// 0xRRGGBB
#define LED_INIT_VALUE 0x000800
#define LED_WINK_VALUE 0x000010
#define LED_MAX_SCALER 15
#define LED_MIN_SCALER 1
LED_INIT_VALUE is the color, that the LED shows whenever it is plugged in. It normally is a green light. So let's change it to red:
// 0xRRGGBB
#define LED_INIT_VALUE 0xFF0800
#define LED_WINK_VALUE 0x000010
#define LED_MAX_SCALER 15
#define LED_MIN_SCALER 1
LED_WINK_VALUE is the color, which is shown, whenever the bottom is pressed. It normally is a blue tone, but let's change it to a yellow:
// 0xRRGGBB
#define LED_INIT_VALUE 0xFF0800
#define LED_WINK_VALUE 0xFFFF00
#define LED_MAX_SCALER 15
#define LED_MIN_SCALER 1
Save the file and then let's try to get the code onto the stick.
Move code to solo hacker
First we have to build cbor. To do this change into the target folder and use the corresponding command.
#Change into correct directory
cd solo/targets/stm32l432/
#Make cbor
make cbor
You should also make sure to check, that your key has the newest solo firmware installed. To check the firmware on the device, use this command:
solo1 key version
To update to the newest version, use this command:
solo1 key update
Note: Sometimes the connection between Mac and key seemed to be broken and you might get an error stating: No solo found. Just unplug the key and plug it back in.
General deployment cycle
In general we will always have to go through these steps:
- Compile code and generate new firmware
- Change device into bootloader mode
- Deploy code to device
Compile code
To compile the code, we will again have to change into our target directory:
#Change into correct directory
cd solo/targets/stm32l432/
It is important to choose the correct build target. Most explanations focus on the build of the firmware and use:
make firmware
As we are using the solo hacker, we will need to use:
make build-hacker
This will generate a file solo.hex, which has the compiled code on it. If you later need to change the bootloader itself, please refer to the documentation.
Deploy code
To deploy the code make sure you are back at the source root.
cd ../..
First we will have to change into bootload modus:
solo1 program aux enter-bootloader
This is needed to be able to load the new firmware on the device. If we forget this step, the solo tool will do it for us in the next step.
This is the moment of truth. We delete the old firmware and deploy the new one with the changed LED lights to the solo key. For this step we will also stay in the source root.
solo1 program bootloader targets/stm32l432/solo.hex
If there is another hex-File, that you want to load, you can just exchange the last argument.
And that's it, now your LED should be red.
To summarize, here are again the steps to update your solo:
- Change code
- Run these commands
#Change into correct directory
cd solo/targets/stm32l432/
#Compile code
make build-hacker
#Change to root
cd ../..
#Enter bootloader mode
solo1 program aux enter-bootloader
#Deploy code
solo1 program bootloader targets/stm32l432/solo.hex