Hawkbit Direct Device Integration API sample¶
The hawkbit update server provides REST resources which are consumed by the device to retrieve software update tasks. This API is based on HTTP standards and a polling mechanism.
This sample shows how to use Hawkbit DDI API in both a polling and manual update mode.
Polling mode run automatically on a predefined period, probing the server for updates and installing them without requiring user intervention. You can access the sample source code for this hawkbit_polling.
Manual mode requires the user to call the server probe and then, if there is an available update, it will install the update. You can access the sample source code for this mode hawkbit_manual
The Zephyr port of
Hawkbitis configured to run on a :ref: Freedom-K64F MCU by default. The application should build and run for other platforms with support internet connection. Some platforms need some modification. Overlay files would be needed to support BLE 6lowpan, 802.15.4 or OpenThread configurations as well as the understanding that most other connectivity options would require an edge gateway of some sort (Border Router, etc).
The MCUboot bootloader is required for
Hawkbitto function properly. More information about the Device Firmware Upgrade subsystem and MCUboot can be found in MCUboot.
Building and Running¶
The below steps describe how to build and run the
Hawkbit sample in
Zephyr. Where examples are given, it is assumed the sample is being build for
the Freedom-K64F Development Kit (
Step 1: Build MCUboot¶
Build MCUboot by following the instructions in the MCUboot documentation page.
Step 2: Flash MCUboot¶
Flash the resulting image file to the 0x0 address of the flash memory. This can be done by,
Step 3: Start the Hawkbit Docker¶
By default, the hawkbit application is set to run on http at port:8080.
sudo docker run -p 8080:8080 hawkbit/hawkbit-update-server:latest \ --hawkbit.dmf.rabbitmq.enabled=false \ --hawkbit.server.ddi.security.authentication.anonymous.enabled=true
This will start the hawkbit server on the host system.Opening your browser to
the server URL,
<your-ip-address>:8080, and logging into the server using
admin as the login and password by default.
Step 4: Build Hawkbit¶
Hawkbit can be built for the frdm_k64f as follows:
# From the root of the zephyr repository west build -b frdm_k64f samples/net/hawkbit -- -DCONF_FILE="prj.conf"
Step 5: Sign the first image¶
From this section onwards you use a binary (
.bin) image format.
west sign -t imgtool -- --key \ ~/zephyrproject/bootloader/mcuboot/root-rsa-2048.pem
The command above creates an image file called
zephyr.signed.bin in the
Step 6: Flash the first image¶
signed.bin file from Step 5 to image slot-0 of your board.
west flash --bin-file build/zephyr/zephyr.signed.bin
Once the image is flashed.In hawkbit server UI, you should see the the frdm_k64f show up in the Targets pane. It’s time to upload a firmware binary to the server, and update it using this UI.
Step 7: Building and signing the test image¶
Then build the sample as usual (see Hello World).
Follow the Step 5 generate an image file called
zephyr.signed.bin in the
Upload the signed image to the server. Click Upload icon in left pane of UI and
create a new Software Module with type Apps (
Then upload the signed image to the server with Upload file Icon.
Click on distribution icon in the left pane of UI and create a new Distribution
with type Apps only (
name:frdm_k64f_update,version:1.0). Assign the
hello_world software module to the created distribution. Click on Deployment
icon in the left pane of UI and assign the
frdm_k64f_update distribution to
Step 8: Run the update¶
Back in the terminal session that you used for debugging the board, type the following command:
And then wait. The board will ping the server, check if there are any new
updates, and then download the update you’ve just created. If everyting goes
fine the message
Image flashed successfully, you can reboot now will be
printed on the terminal.
Step 9: Reboot the system¶
In the terminal you used for debugging the board, type the following command:
kernel reboot cold
Your board will reboot and then start with the new image. After rebooting, the
board will automatically ping the server again and the message
available will be printed on the terminal.
Step 10: Clone and build hawkbit with https¶
Below steps clone and build the hawkbit with self-signed certificate to support https.
git clone https://github.com/eclipse/hawkbit.git cd hawkbit/hawkbit-runtime/hawkbit-update-server/src/main/resources
Generate the private key
openssl genrsa -des3 -out server.key 2048
Generate the CSR
openssl req -new -key server.key -out server.csr
Once you run the command, it will prompt you to enter your Country,
State, City, Company name and enter the Comman Name field with
Generate the self-signed x509 certificate suitable to use on web server.
openssl x509 -req -days 365 -in server.csr -signkey server.key -out server.crt
Generate pem file from generated server.key and server.crt
cat server.key > server.pem cat server.crt >> server.pem
Generate .pkcs12 file
openssl pkcs12 -export -in server.pem -out keystore.pkcs12
Following command imports a .p12 into pkcs12 Java keystore
keytool -importkeystore -srckeystore keystore.pkcs12 -srcstoretype pkcs12 \ -destkeystore hb-pass.jks -deststoretype pkcs12 \ -alias 1 -deststorepass <password_of_p12>
Edit the hawkbit application.properties file
Change authentication security from false to true.
Enter the https details at last
server.hostname=localhost server.port=8443 hawkbit.artifact.url.protocols.download-http.protocol=https hawkbit.artifact.url.protocols.download-http.port=8443 security.require-ssl=true server.use-forward-headers=true server.ssl.key-store= <hb-pass.jks file location> server.ssl.key-store-type=JKS server.ssl.key-password= <password_of_key> server.ssl.key-store-password= <password_of_key_store> server.ssl.protocol=TLS server.ssl.enabled-protocols=TLSv1.2 server.ssl.ciphers=TLS_RSA_WITH_AES_256_CBC_SHA256, TLS_RSA_WITH_AES_256_CBC_SHA
cd ~/hawkbit mvn clean install -DskipTests=true
Once the build is successful, run hawkbit
java -jar ./hawkbit-runtime/hawkbit-update-server/target/ \ hawkbit-update-server-#version#-SNAPSHOT.jar
Step 11: Build Hawkbit HTTPS¶
Convert the server.pem file to self_sign.der and place the der file in hawkbit/src directory
Hawkbit https can be built for the frdm_k64f as follows:
# From the root of the zephyr repository west build -b frdm_k64f samples/net/hawkbit -- -DCONF_FILE="prj.conf overlay-tls.conf"
Repeat the steps from 5 to 9, to update the device over https.