Men 8325 review zephyr getting started #2599
Conversation
Signed-off-by: Eystein Måløy Stenberg <[email protected]>
Changelog: Title Ticket: MEN-8325 Signed-off-by: Michal Kopczan <[email protected]>
|
|
||
| **Prepare the Espressif firmware blobs:** We will use WiFi, which requires firmware blobs to be prepared. Do so by running: | ||
| ```bash | ||
| pip install -r zephyr/scripts/requirements.txt |
There was a problem hiding this comment.
Because we use a specific version of zephyr, v.4.0.0 this is a part of zephyr's doc that will not change without our input - no risk of adding too much of zephyr's docs to our document.
Current zephyr getting started guide linked at the top of this document does not mention zephyr/scripts/requirements, as it was replaced in zephyr 4.1.0 by "west packages".
There was a problem hiding this comment.
Is it really necessary for us to specify this requirement at all? It's a part of the Zephyr's getting started guide, so as long as the same environment is sourced (which you added a comment about), then you should have the requirements, right?
There was a problem hiding this comment.
If we need to install requirements then how about west zephyr-export or west sdk install?
There was a problem hiding this comment.
Since we agreed to point the user to a specific version of Zephyr's getting started, there will be no need to mention the requirements.txt in our doc, as it is present in zephyr's guide version 4.0.0.
I pointed the user to v4.0.0 of zephyr's getting started, and reverted this change.
| You should see log output from MCUboot and then the Zephyr application. On first boot, the logs may show the device connecting to WiFi and attempting to authorize with the Mender server (using the provided tenant token). If all goes well, it will log something like `<err> mender: [401] Unauthorized: dev auth: unauthorized`. Those authentication errors are expected at this step as the device is not yet authorized in the Mender server. | ||
| You should see log output from MCUboot and then the Zephyr application. On first boot, the logs may show the device connecting to WiFi and attempting to authorize with the Mender server (using the provided tenant token). If all goes well, it will log something like `<err> mender: [401] Unauthorized: dev auth: unauthorized`. Those authentication errors are expected at this step as the device is not yet authorized in the Mender Server. | ||
|
|
||
| !!! If the device seems to get stuck while starting after flashing, e.g. while bringing up network, try to disconnect power (USB) and reconnect. A hard power reset is sometimes needed after reflashing. |
There was a problem hiding this comment.
Is this true? I've never had to to this after flashing 🤔
There was a problem hiding this comment.
I have never see this as well.
There was a problem hiding this comment.
As discussed, I will reevaluate this part with my board with different usb cable, power source. I will also check with the two boards I borrowed from the office. I'll let you know the result.
There was a problem hiding this comment.
Reevaluated with a different board, and the issue persists.
However, when I used my phone as a wifi hotspot, connection is established every time. Seems to be maybe a problem with my router? The change about rebooting came originally from Eystein, so he also encountered this issue. Maybe it's a more widespread compatibility issue.
We could add something like "If the device seems to get stuck while starting on Waiting for network up..., try using a different WiFi router, e.g. smartphone WiFi hotspot". But I'm not sure if we want to suggest this way there are issues with our software. What do you think?
There was a problem hiding this comment.
We could add something like "If the device seems to get stuck while starting on Waiting for network up..., try using a different WiFi router, e.g. smartphone WiFi hotspot".
I don't know about the others, but I prefer this. I am not so sure this is a fault of our code, but rather the fault of the module we're using. I would at least not say A hard power reset is sometimes needed after reflashing.
There was a problem hiding this comment.
Yeah, we can remove the last part I think as well (A hard power reset is sometimes needed after reflashing.). Makes it seem a bit flaky (which it is though).
| source ~/zephyrproject/.venv/bin/activate | ||
| ``` | ||
|
|
||
| !!! Remember to activate the virtual environment every time you start working. |
There was a problem hiding this comment.
Maybe Remember to activate the virtual environment every time you open a terminal.?
| These will be passed into the build to configure the device's WiFi connection and authentication with hosted Mender. The example uses these to configure the Zephyr WiFi driver and the Mender client token. | ||
| These will be passed into the build to configure the device's WiFi connection and authentication with hosted Mender. The example uses these to configure the Zephyr WiFi driver and the Mender Server Tenant Token. | ||
|
|
||
| **Choose Mender server:** By default, US Mender server is configured. If you're using EU Mender server, change the project to use it. Open `~/mender-mcu-workspace/mender-mcu-integration/prj.conf` in a text editor. Change the line |
There was a problem hiding this comment.
s/change the project/update the project configuration/
There was a problem hiding this comment.
Also, for consistency with other parts use full versions of verbs so "If you are using (...)"
There was a problem hiding this comment.
And maybe mention hosted, so "By default, the US instance of hosted Mender server is configured. If you are using EU hosted Mender Server instance (...)"
There was a problem hiding this comment.
Done. Also made use of "Mender server" consistent. Before the "server" was sometimes capitalized, sometimes not, i.e. "Mender Server" and "Mender server".
Now, "Mender server" is always used. If it should be capitalized, let me know.
| You should see log output from MCUboot and then the Zephyr application. On first boot, the logs may show the device connecting to WiFi and attempting to authorize with the Mender server (using the provided tenant token). If all goes well, it will log something like `<err> mender: [401] Unauthorized: dev auth: unauthorized`. Those authentication errors are expected at this step as the device is not yet authorized in the Mender server. | ||
| You should see log output from MCUboot and then the Zephyr application. On first boot, the logs may show the device connecting to WiFi and attempting to authorize with the Mender server (using the provided tenant token). If all goes well, it will log something like `<err> mender: [401] Unauthorized: dev auth: unauthorized`. Those authentication errors are expected at this step as the device is not yet authorized in the Mender Server. | ||
|
|
||
| !!! If the device seems to get stuck while starting after flashing, e.g. while bringing up network, try to disconnect power (USB) and reconnect. A hard power reset is sometimes needed after reflashing. |
There was a problem hiding this comment.
I have never see this as well.
| @@ -99,6 +129,10 @@ When the device starts up with the Mender client, it will automatically try to c | |||
|
|
|||
|  | |||
|
|
|||
|
|
|||
| !!! If you do not see your device, check your device's network configuration, hosted Mender address (this tutorial assumes you are using the (US server)[https://hosted.mender.io?target=_blank], not the (EU server)[https://eu.hosted.mender.io?target=_blank]) and Tenant Token. Go back to the terminal of your device, and look for unexpected error messages. To enable debug log-level or configure network settings for your device, see [Mender's documentation page on Zephyr configuration](../../../06.Operating-System-updates-Zephyr/05.Configuration/docs.md). | |||
There was a problem hiding this comment.
I would say "To enable debug-level logging (...)"
|
|
||
| ```bash | ||
| export ARTIFACT_NAME="release-2" | ||
| west build --domain mender-mcu-integration -- -DCONFIG_MENDER_ARTIFACT_NAME=\"$ARTIFACT_NAME\" | ||
| cd ~/mender-mcu-workspace | ||
| west build -p auto -b esp32s3_devkitc/esp32s3/procpu --sysbuild --domain mender-mcu-integration -- -DCONFIG_MENDER_ARTIFACT_NAME=\"$ARTIFACT_NAME\" |
There was a problem hiding this comment.
Why do we need --sysbuild here?
There was a problem hiding this comment.
When I tried using the old version with "--domain" only it did not work, i.e. did not compile.
I found on the internet, that "--domain" is used only in tandem with "--sysbuild" - it tells sysbuild to build only one domain.
Did you have other experience, i.e. did using "--domain" only work for you?
There was a problem hiding this comment.
--domain is used in multi-domain builds, e.g. sysbuild, but you shouldn't need to pass --sysbuild again once you've built mcu-boot 🤔 It seems like the errors you get is related to the caching of the artifact name variable by cmake? If you run it without -DCONFIG_MENDER_ARTIFACT_NAME=\"$ARTIFACT_NAME\" it compiles. To not make it too complicated I think it's fine to include sysbuild here since it works and correctly updates the artifact name, but you don't need to specify -p auto -b esp32s3_devkitc/esp32s3/procpu again
|
|
||
| **Prepare the Espressif firmware blobs:** We will use WiFi, which requires firmware blobs to be prepared. Do so by running: | ||
| ```bash | ||
| pip install -r zephyr/scripts/requirements.txt |
There was a problem hiding this comment.
If we need to install requirements then how about west zephyr-export or west sdk install?
|
@estenberg Maybe you can proof read and check this one as well. |
Changelog: Title Ticket: MEN-8325 Signed-off-by: Michal Kopczan <[email protected]>
| @@ -7,34 +7,49 @@ taxonomy: | |||
|
|
|||
| We will build and flash a Zephyr firmware for an ESP32-S3-DevKitC board. By the end of this section, your device will boot and show up as **pending** in your Mender server (hosted Mender), ready to be accepted. | |||
|
|
|||
| This guide assumes you are using Ubuntu, as Zephyr getting started guide provides instruction for Ubuntu and Mender Artifact tools provides .deb packages. | |||
There was a problem hiding this comment.
Mender Artifact doesn't provide .deb packages, but the download page gives deb packages to install Mender Artifact
There was a problem hiding this comment.
This will change too: we will do repositories for Ubuntu, not packages in the future.
Would change to a note:
!!! This guide assumes you are using Ubuntu, as it is a well supported workstation environment both for Zephyr and Mender.
There was a problem hiding this comment.
Also note that such note will go out of date, because we'll support macOS repos soon, and Zephyr already supports it.
| @@ -59,20 +86,19 @@ Now we will compile the Zephyr application with Mender support and flash it to t | |||
| **Build the firmware** using west. In the same terminal (ensure the environment variables from above are still set), run: | |||
|
|
|||
| ```bash | |||
| west build --sysbuild mender-mcu-integration -- \ | |||
| west build -b esp32s3_devkitc/esp32s3/procpu --sysbuild mender-mcu-integration -- \ | |||
There was a problem hiding this comment.
I know this is Eysteins commit, but are we adding this back on purpose? In MEN-8014 we made the esp32s3 the default board, so we removed the need to explicitly having to set the board when building, see mendersoftware/mender-mcu-integration#45
There was a problem hiding this comment.
I didn't think through it too much then.
But I think it is good to have, as it shows more clearly how to switch boards later, and in case we change the default at some point this won't be affected.
|
|
||
| Let's break down this command: | ||
| * `west build --sysbuild mender-mcu-integration` tells west to build the project (located in the mender-mcu-integration directory) using [Zephyr's system build](https://docs.zephyrproject.org/latest/build/sysbuild/index.html?target=_blank) (which will compile MCUboot and the app together). | ||
| * `--sysbuild mender-mcu-integration` tells west to build the project (located in the ~/mender-mcu-integration directory) using [Zephyr's system build](https://docs.zephyrproject.org/latest/build/sysbuild/index.html?target=_blank) (which will compile MCUboot and the app together). |
There was a problem hiding this comment.
Also Eysteins commit, but I don't think it makes sense to remove west build here.
There was a problem hiding this comment.
it was related to the above change I think; if -b parameter is added then the full line would be "west build -b esp32s3_devkitc/esp32s3/procpu --sysbuild mender-mcu-integration".
To me it makes sense to keep this as-is; we're just talking about --sysbuild here, not the rest of the command.
| You should see log output from MCUboot and then the Zephyr application. On first boot, the logs may show the device connecting to WiFi and attempting to authorize with the Mender server (using the provided tenant token). If all goes well, it will log something like `<err> mender: [401] Unauthorized: dev auth: unauthorized`. Those authentication errors are expected at this step as the device is not yet authorized in the Mender server. | ||
| You should see log output from MCUboot and then the Zephyr application. On first boot, the logs may show the device connecting to WiFi and attempting to authorize with the Mender server (using the provided tenant token). If all goes well, it will log something like `<err> mender: [401] Unauthorized: dev auth: unauthorized`. Those authentication errors are expected at this step as the device is not yet authorized in the Mender Server. | ||
|
|
||
| !!! If the device seems to get stuck while starting after flashing, e.g. while bringing up network, try to disconnect power (USB) and reconnect. A hard power reset is sometimes needed after reflashing. |
There was a problem hiding this comment.
We could add something like "If the device seems to get stuck while starting on Waiting for network up..., try using a different WiFi router, e.g. smartphone WiFi hotspot".
I don't know about the others, but I prefer this. I am not so sure this is a fault of our code, but rather the fault of the module we're using. I would at least not say A hard power reset is sometimes needed after reflashing.
|
|
||
| ```bash | ||
| export ARTIFACT_NAME="release-2" | ||
| west build --domain mender-mcu-integration -- -DCONFIG_MENDER_ARTIFACT_NAME=\"$ARTIFACT_NAME\" | ||
| cd ~/mender-mcu-workspace | ||
| west build -p auto -b esp32s3_devkitc/esp32s3/procpu --sysbuild --domain mender-mcu-integration -- -DCONFIG_MENDER_ARTIFACT_NAME=\"$ARTIFACT_NAME\" |
There was a problem hiding this comment.
--domain is used in multi-domain builds, e.g. sysbuild, but you shouldn't need to pass --sysbuild again once you've built mcu-boot 🤔 It seems like the errors you get is related to the caching of the artifact name variable by cmake? If you run it without -DCONFIG_MENDER_ARTIFACT_NAME=\"$ARTIFACT_NAME\" it compiles. To not make it too complicated I think it's fine to include sysbuild here since it works and correctly updates the artifact name, but you don't need to specify -p auto -b esp32s3_devkitc/esp32s3/procpu again
| @@ -7,34 +7,49 @@ taxonomy: | |||
|
|
|||
| We will build and flash a Zephyr firmware for an ESP32-S3-DevKitC board. By the end of this section, your device will boot and show up as **pending** in your Mender server (hosted Mender), ready to be accepted. | |||
|
|
|||
| This guide assumes you are using Ubuntu, as Zephyr getting started guide provides instruction for Ubuntu and Mender Artifact tools provides .deb packages. | |||
There was a problem hiding this comment.
This will change too: we will do repositories for Ubuntu, not packages in the future.
Would change to a note:
!!! This guide assumes you are using Ubuntu, as it is a well supported workstation environment both for Zephyr and Mender.
| @@ -7,34 +7,49 @@ taxonomy: | |||
|
|
|||
| We will build and flash a Zephyr firmware for an ESP32-S3-DevKitC board. By the end of this section, your device will boot and show up as **pending** in your Mender server (hosted Mender), ready to be accepted. | |||
|
|
|||
| This guide assumes you are using Ubuntu, as Zephyr getting started guide provides instruction for Ubuntu and Mender Artifact tools provides .deb packages. | |||
There was a problem hiding this comment.
Also note that such note will go out of date, because we'll support macOS repos soon, and Zephyr already supports it.
| @@ -59,20 +86,19 @@ Now we will compile the Zephyr application with Mender support and flash it to t | |||
| **Build the firmware** using west. In the same terminal (ensure the environment variables from above are still set), run: | |||
|
|
|||
| ```bash | |||
| west build --sysbuild mender-mcu-integration -- \ | |||
| west build -b esp32s3_devkitc/esp32s3/procpu --sysbuild mender-mcu-integration -- \ | |||
There was a problem hiding this comment.
I didn't think through it too much then.
But I think it is good to have, as it shows more clearly how to switch boards later, and in case we change the default at some point this won't be affected.
|
|
||
| Let's break down this command: | ||
| * `west build --sysbuild mender-mcu-integration` tells west to build the project (located in the mender-mcu-integration directory) using [Zephyr's system build](https://docs.zephyrproject.org/latest/build/sysbuild/index.html?target=_blank) (which will compile MCUboot and the app together). | ||
| * `--sysbuild mender-mcu-integration` tells west to build the project (located in the ~/mender-mcu-integration directory) using [Zephyr's system build](https://docs.zephyrproject.org/latest/build/sysbuild/index.html?target=_blank) (which will compile MCUboot and the app together). |
There was a problem hiding this comment.
it was related to the above change I think; if -b parameter is added then the full line would be "west build -b esp32s3_devkitc/esp32s3/procpu --sysbuild mender-mcu-integration".
To me it makes sense to keep this as-is; we're just talking about --sysbuild here, not the rest of the command.
| You should see log output from MCUboot and then the Zephyr application. On first boot, the logs may show the device connecting to WiFi and attempting to authorize with the Mender server (using the provided tenant token). If all goes well, it will log something like `<err> mender: [401] Unauthorized: dev auth: unauthorized`. Those authentication errors are expected at this step as the device is not yet authorized in the Mender server. | ||
| You should see log output from MCUboot and then the Zephyr application. On first boot, the logs may show the device connecting to WiFi and attempting to authorize with the Mender server (using the provided tenant token). If all goes well, it will log something like `<err> mender: [401] Unauthorized: dev auth: unauthorized`. Those authentication errors are expected at this step as the device is not yet authorized in the Mender Server. | ||
|
|
||
| !!! If the device seems to get stuck while starting after flashing, e.g. while bringing up network, try to disconnect power (USB) and reconnect. A hard power reset is sometimes needed after reflashing. |
There was a problem hiding this comment.
Yeah, we can remove the last part I think as well (A hard power reset is sometimes needed after reflashing.). Makes it seem a bit flaky (which it is though).
Commits will need to be squashed before merging. So far I left Eystein's commit for easier understanding of the changes.
I tried to limit referencing zephyr's documentation as much as possible, while at the same time, making our instructions truly a step-by-step guide.
Let me know if we should approach it differently.
docs: Zephyr getting started guide improvements