1.. zephyr:code-sample:: hawkbit-api
2   :name: Eclipse hawkBit Direct Device Integration API
3   :relevant-api: hawkbit
4
5   Update a device using Eclipse hawkBit DDI API.
6
7Overview
8********
9
10The Eclipse hawkBit update server provides REST resources which are consumed by the
11device to retrieve software update tasks. This API is based on HTTP standards
12and a polling mechanism.
13
14This sample shows how to use hawkBit DDI API in both a polling and manual
15update mode.
16
17Polling mode run automatically on a predefined period, probing the server
18for updates and installing them without requiring user intervention. You can
19access the sample source code for this hawkbit_polling.
20
21Manual mode requires the user to call the server probe and then, if there is
22an available update, it will install the update. You can access the sample
23source code for this mode hawkbit_manual
24
25Caveats
26*******
27
28* The Zephyr port of hawkBit is configured to run on a
29  :zephyr:board:`Freedom-K64F <frdm_k64f>` MCU by default. The application should
30  build and run for other platforms with support internet connection. Some
31  platforms need some modification. Overlay files would be needed to support
32  BLE 6lowpan, 802.15.4 or OpenThread configurations as well as the
33  understanding that most other connectivity options would require an edge
34  gateway of some sort (Border Router, etc).
35
36* The MCUboot bootloader is required for hawkBit to function properly.
37  More information about the Device Firmware Upgrade subsystem and MCUboot
38  can be found in :ref:`mcuboot`.
39
40Building and Running
41********************
42
43The below steps describe how to build and run the hawkBit sample in
44Zephyr. Where examples are given, it is assumed the sample is being build for
45the Freedom-K64F Development Kit (``BOARD=frdm_k64f``).
46
47Step 1: Build MCUboot
48=====================
49
50Build MCUboot by following the instructions in the :ref:`mcuboot` documentation
51page.
52
53Step 2: Flash MCUboot
54=====================
55
56Flash the resulting image file to the 0x0 address of the flash memory. This can
57be done by,
58
59.. code-block:: console
60
61   west flash
62
63Step 3: Start the hawkBit Docker
64================================
65
66By default, the hawkbit application is set to run on http at port:8080.
67
68.. code-block:: console
69
70   sudo docker run -p 8080:8080 hawkbit/hawkbit-update-server:latest \
71   --hawkbit.dmf.rabbitmq.enabled=false \
72   --hawkbit.server.ddi.security.authentication.anonymous.enabled=true
73
74This will start the hawkbit server on the host system.Opening your browser to
75the server URL, ``<your-ip-address>:8080``, and logging into the server using
76``admin`` as the login and password by default.
77
78Step 4: Build hawkBit
79=====================
80
81hawkBit can be built for the :zephyr:board:`Freedom-K64F <frdm_k64f>` as follows:
82
83.. zephyr-app-commands::
84    :zephyr-app: samples/subsys/mgmt/hawkbit
85    :board: frdm_k64f
86    :conf: "prj.conf"
87    :goals: build
88
89If you want to build it with the ability to set the hawkBit server address
90and port during runtime, you can use the following command:
91
92.. zephyr-app-commands::
93    :zephyr-app: samples/subsys/mgmt/hawkbit
94    :board: frdm_k64f
95    :conf: "prj.conf overlay-runtime.conf"
96    :goals: build
97
98.. _hawkbit_sample_sign:
99
100The firmware will be signed automatically by the build system with the
101``root-rsa-2048.pem`` key. The key is located in the MCUboot repository.
102
103Step 5: Flash the first image
104=============================
105
106Upload the :file:`zephyr.signed.confirmed.bin` file to image slot-0
107of your board.
108
109.. code-block:: console
110
111   west flash --bin-file build/zephyr/zephyr.signed.confirmed.bin
112
113Once the image is flashed and booted, the sample will print the image build
114time to the console. After it connects to the internet, in hawkbit server UI,
115you should see the ``frdm_k64f`` show up in the Targets pane. It's time to
116upload a firmware binary to the server, and update it using this UI.
117
118Step 6: Building and signing the test image
119===========================================
120
121The easiest way to test the functionality of hawkBit is to repeat step 4 to
122build the sample again, so that the build time will be different.
123
124This time you need the file :file:`zephyr.signed.bin` from the build directory.
125
126Upload the signed image to the server. Click Upload icon in left pane of UI and
127create a new Software Module with type Apps (``name:hawkbit,version:1.0.1``).
128Then upload the signed image to the server with Upload file Icon.
129
130Click on distribution icon in the left pane of UI and create a new Distribution
131with type Apps only (``name:frdm_k64f_update,version:1.0.1``). Assign the
132hawkBit software module to the created distribution. Click on Deployment
133icon in the left pane of UI and assign the ``frdm_k64f_update`` distribution to
134the target ``frdm_k64f``.
135
136Step 7: Run the update
137======================
138
139Back in the terminal session that you used for debugging the board, type the
140following command:
141
142.. code-block:: console
143
144   hawkbit run
145
146And then wait. The board will ping the server, check if there are any new
147updates, and then download the update you've just created. If everything goes
148fine the message ``Update installed`` will be printed on the terminal.
149
150Your board will reboot automatically and then start with the new image. After rebooting, the
151board will print a different image build time then automatically ping the server
152again and the message ``Image is already updated`` will be printed on the terminal.
153
154Step 8: Clone and build hawkbit with https
155==========================================
156
157Below steps clone and build the hawkbit with self-signed certificate
158to support https.
159
160.. code-block:: console
161
162   git clone https://github.com/eclipse/hawkbit.git
163   cd hawkbit/hawkbit-runtime/hawkbit-update-server/src/main/resources
164
165* Generate the private key
166
167.. code-block:: console
168
169   openssl genrsa -des3 -out server.key 2048
170
171* Generate the CSR
172
173.. code-block:: console
174
175   openssl req -new -key server.key -out server.csr
176
177Once you run the command, it will prompt you to enter your Country,
178State, City, Company name and enter the Command Name field with
179``<your-ip-address>``.
180
181* Generate the self-signed x509 certificate suitable to use on web server.
182
183.. code-block:: console
184
185   openssl x509 -req -days 365 -in server.csr -signkey server.key -out server.crt
186
187* Generate pem file from generated server.key and server.crt
188
189.. code-block:: console
190
191   cat server.key > server.pem
192   cat server.crt >> server.pem
193
194* Generate .pkcs12 file
195
196.. code-block:: console
197
198   openssl pkcs12 -export -in server.pem -out keystore.pkcs12
199
200* Following command imports a .p12 into pkcs12 Java keystore
201
202.. code-block:: console
203
204   keytool -importkeystore -srckeystore keystore.pkcs12 -srcstoretype pkcs12 \
205   -destkeystore hb-pass.jks -deststoretype pkcs12 \
206   -alias 1 -deststorepass <password_of_p12>
207
208* Edit the hawkbit application.properties file
209
210.. code-block:: console
211
212   vi application.properties
213
214Change authentication security from false to true.
215
216.. code-block:: console
217
218   hawkbit.server.ddi.security.authentication.anonymous.enabled=true
219
220* Enter the https details at last
221
222.. code-block:: console
223
224   server.hostname=localhost
225   server.port=8443
226   hawkbit.artifact.url.protocols.download-http.protocol=https
227   hawkbit.artifact.url.protocols.download-http.port=8443
228
229   security.require-ssl=true
230   server.use-forward-headers=true
231
232   server.ssl.key-store=  <hb-pass.jks file location>
233   server.ssl.key-store-type=JKS
234   server.ssl.key-password= <password_of_key>
235   server.ssl.key-store-password= <password_of_key_store>
236
237   server.ssl.protocol=TLS
238   server.ssl.enabled-protocols=TLSv1.2
239   server.ssl.ciphers=TLS_RSA_WITH_AES_256_CBC_SHA256,
240                      TLS_RSA_WITH_AES_256_CBC_SHA
241
242* Start Compile
243
244.. code-block:: console
245
246   cd ~/hawkbit
247
248   mvn clean install -DskipTests=true
249
250* Once the build is successful, run hawkbit
251
252.. code-block:: console
253
254   java -jar ./hawkbit-runtime/hawkbit-update-server/target/ \
255        hawkbit-update-server-#version#-SNAPSHOT.jar
256
257Step 9: Build hawkBit HTTPS
258===========================
259
260* Convert the server.pem file to self_sign.der and place the der file in
261  hawkbit/src directory
262
263``hawkBit https`` can be built for the :zephyr:board:`Freedom-K64F <frdm_k64f>` as follows:
264
265.. zephyr-app-commands::
266    :zephyr-app: samples/subsys/mgmt/hawkbit
267    :board: frdm_k64f
268    :conf: "prj.conf overlay-tls.conf"
269    :goals: build
270
271Repeat the steps from 5 to 7, to update the device over https.
272