diff --git a/content/learning-paths/embedded-and-microcontrollers/nxp-imx8uplus-gglite-zephyr-combined-part3/.python-version b/content/learning-paths/embedded-and-microcontrollers/nxp-imx8uplus-gglite-zephyr-combined-part3/.python-version new file mode 100644 index 0000000000..a616492698 --- /dev/null +++ b/content/learning-paths/embedded-and-microcontrollers/nxp-imx8uplus-gglite-zephyr-combined-part3/.python-version @@ -0,0 +1 @@ +2.7.18 diff --git a/content/learning-paths/embedded-and-microcontrollers/nxp-imx8uplus-gglite-zephyr-combined-part3/_index.md b/content/learning-paths/embedded-and-microcontrollers/nxp-imx8uplus-gglite-zephyr-combined-part3/_index.md new file mode 100644 index 0000000000..d3bf0969f6 --- /dev/null +++ b/content/learning-paths/embedded-and-microcontrollers/nxp-imx8uplus-gglite-zephyr-combined-part3/_index.md @@ -0,0 +1,53 @@ +--- +title: "Part 3: NXP FRDM i.MX 8M Plus \u2014 Deploy BMP280 temperature sensing and an AWS IoT Core bridge" +draft: true +cascade: + draft: true +description: "Deploy MCU firmware and a Linux bridge as S3-backed custom Greengrass components." +minutes_to_complete: 120 +who_is_this_for: Embedded Linux developers connecting an NXP application processor and MCU to AWS IoT Greengrass. +learning_objectives: + - "Read the external temperature via the BMP280 sensor on the Cortex-M7 using Zephyr RTOS" + - "Deploy two S3-backed AWS Greengrass components to install and run the Zephyr app and its Yocto bridge component" + - "Publish JSON messages to nxp/imx8mplus/temperature/external within AWS IoTCore containing the read temperature from the sensor" + - "Remove both apps and verify cleanup and redeployment capabilities" +prerequisites: + - "NXP FRDM i.MX 8M Plus with an appropriate power supply, microSD card and reader, wired Ethernet, and its debug USB cable" + - An Ubuntu 22.04 or 24.04 host on x86_64 (amd64) or arm64 (aarch64) with 32 GB RAM and 300–500 GB free space on a Linux filesystem + - AWS CLI v2 and an account permitted to manage IoT identities, Greengrass deployments, and component artifacts + - Complete Part 1 for this same board; retain its image, identity and thing group + - Python 3.12 or newer, west, CMake, Ninja, and Zephyr SDK 0.17.4 on the Ubuntu development host + - Complete Part 2 and verify a repeatable application MCU start and stop. + - An external BMP280 I2C module plus jumper wires +author: Doug Anson +generate_summary_faq: true +rerun_summary: false +rerun_faqs: false +skilllevels: Advanced +subjects: Embedded Linux +armips: + - Cortex-A + - Cortex-M +operatingsystems: + - Linux + - RTOS +tools_software_languages: + - Yocto Project + - AWS IoT Greengrass + - Python + - Zephyr + - C +further_reading: + - resource: + title: "NXP FRDM i.MX 8M Plus Part 1 \u2014 Yocto and Greengrass" + link: /learning-paths/embedded-and-microcontrollers/nxp-imx8uplus-yocto-gglite-part1/ + type: learningpath + - resource: + title: "NXP FRDM i.MX 8M Plus Part 2 \u2014 Zephyr alongside Linux" + link: /learning-paths/embedded-and-microcontrollers/nxp-imx8uplus-yocto-zephyr-part2/ + type: learningpath +### FIXED, DO NOT MODIFY +weight: 1 +layout: "learningpathall" +learning_path_main_page: "yes" +--- diff --git a/content/learning-paths/embedded-and-microcontrollers/nxp-imx8uplus-gglite-zephyr-combined-part3/_next-steps.md b/content/learning-paths/embedded-and-microcontrollers/nxp-imx8uplus-gglite-zephyr-combined-part3/_next-steps.md new file mode 100644 index 0000000000..e20dfa6d43 --- /dev/null +++ b/content/learning-paths/embedded-and-microcontrollers/nxp-imx8uplus-gglite-zephyr-combined-part3/_next-steps.md @@ -0,0 +1,8 @@ +--- +# ================================================================================ +# FIXED, DO NOT MODIFY THIS FILE +# ================================================================================ +weight: 21 +title: "Next Steps" +layout: "learningpathall" +--- diff --git a/content/learning-paths/embedded-and-microcontrollers/nxp-imx8uplus-gglite-zephyr-combined-part3/bridge.md b/content/learning-paths/embedded-and-microcontrollers/nxp-imx8uplus-gglite-zephyr-combined-part3/bridge.md new file mode 100644 index 0000000000..2c6b8bb1d9 --- /dev/null +++ b/content/learning-paths/embedded-and-microcontrollers/nxp-imx8uplus-gglite-zephyr-combined-part3/bridge.md @@ -0,0 +1,51 @@ +--- +title: "NXP FRDM i.MX 8M Plus: Package the RPMsg-to-IoT-Core bridge" +description: "Prepare offline dependencies and a foreground Linux telemetry bridge." +weight: 5 +layout: "learningpathall" +--- + +## Introduction to the RPMsg-to-IoTCore relay/bridge + +Within the bridge code, `components/bridge.py` waits for `/dev/nxp-temperature`, opens the RPMsg TTY in raw mode, and sends a host greeting to establish its endpoint address. It accepts only newline-delimited `nxp.external.temperature` schema-1 frames with valid integer fields and BMP280-range values. It publishes each accepted sample through Greengrass IPC `PublishToIoTCore`, with QoS 1, to **`nxp/imx8mplus/temperature/external`**. The boards existing Greengrass environment, by default, supplies and manages the MQTT/TLS authentication for the bridge into AWS IoTCore. + +JSON messages published to AWS IoTCore will resemble this: +```json +{"schemaVersion":1,"thingName":"MyNXPIMX8MPlus","sensor":"BMP280","location":"external","temperatureC":25.08,"sequence":12,"mcuUptimeMs":60320,"linuxBootId":"example-boot-id","timestamp":"2026-10-29T18:00:00.123+00:00"} +``` + +The timestamp is Linux's UTC receipt time. Sequence and MCU uptime restart with the firmware; QoS 1 can duplicate deliveries. Publish failures are logged and the affected sample is dropped. + +## Build and stage our artifacts for the bridge + +On the Ubuntu host, type: + +```bash +source "$HOME/nxp-imx8uplus-zephyr-venv/bin/activate" +cd "$HOME/nxp-imx8uplus-temperature-part3" +sh tools/stage.sh build/temperature/zephyr/zephyr.elf 313 +find staging -type f -print +``` + +Replace `313` with the board's actual python interpreter version if different (should not need to be changed though). The script downloads `awsiotsdk==1.26.0` and its pinned `awscrt==0.28.1` wheel for Linux AArch64, independent of the build host's architecture. + +Before staging, the script runs the ELF inspector using the Zephyr virtual +environment's `pyelftools`. An old failing ELF is rejected before artifacts are +copied. The firmware component has three artifacts: ELF, manager and Linux +preflight helper. The bridge has four: source, lifecycle script, universal SDK wheel, and AArch64 CRT wheel. + +The component version comes from `release.json` (currently `1.0.1`). Staging, +recipe generation and the deployment page use that same value. Keep earlier +staged versions for rollback; the uploader selects only the current plan. + +## Understand the AWS Greengrass component install, run, and removal + +Greengrass downloads S3 artifacts before the install phase. The bridge install script uses `pip --no-index --no-cache-dir --find-links` and a private digest-named target directory under component work storage. Python and pip come from the Part 1 image. + +The foreground run supervisor starts Python, keeps it in the component control group, and handles termination. Python closes its RPMsg TTY and IPC client; the supervisor removes the private installed directory. It can reinstall from immutable artifacts on the next run. The firmware manager uses a different endpoint for stop control. + +The recipes run with root privileges in this development image to access serial and remoteproc resources. A production image should grant the bridge a suitable device group and reserve root only for operations that require it. + +## What you have learned + +You can explain the bridge's RPMsg greeting and schema design as well as build/stage our bridge for inclusion into an AWS IoT Greengrass custom component. \ No newline at end of file diff --git a/content/learning-paths/embedded-and-microcontrollers/nxp-imx8uplus-gglite-zephyr-combined-part3/cleanup.md b/content/learning-paths/embedded-and-microcontrollers/nxp-imx8uplus-gglite-zephyr-combined-part3/cleanup.md new file mode 100644 index 0000000000..3720f71dd8 --- /dev/null +++ b/content/learning-paths/embedded-and-microcontrollers/nxp-imx8uplus-gglite-zephyr-combined-part3/cleanup.md @@ -0,0 +1,75 @@ +--- +title: "NXP FRDM i.MX 8M Plus: Remove the apps and verify cleanup" +description: "Revise desired state and prove repeatable application-MCU cleanup." +weight: 8 +layout: "learningpathall" +--- + +## Shutting down both applications via revised deployment + +Retrieve the latest deployment ID again, since another change may have occurred. On the Ubuntu host: + +```bash +aws greengrassv2 list-deployments --target-arn "$GROUP_ARN" --history-filter LATEST_ONLY +``` + +Set CURRENT_DEPLOYMENT_ID to the latest deployment ID found above: + +```bash +export CURRENT_DEPLOYMENT_ID=YOUR_LATEST_GROUP_DEPLOYMENT_ID +``` + +Now, lets revise the deployment with an update effectively de-selecting both custom components: + +```bash +aws greengrassv2 get-deployment --deployment-id "$CURRENT_DEPLOYMENT_ID" > current-deployment.json +python3 - <<'PYTHON' +import json,os +from pathlib import Path +current=json.loads(Path('current-deployment.json').read_text()) +assert current['targetArn']==os.environ['GROUP_ARN'] +components=current.get('components',{}).copy() +components.pop('com.arm.NXPIMX8MPlus.ZephyrExternalTemperature',None) +components.pop('com.arm.NXPIMX8MPlus.ExternalTemperatureBridge',None) +Path('remove-deployment.json').write_text(json.dumps({'targetArn':os.environ['GROUP_ARN'],'deploymentName':'Remove NXP FRDM i.MX 8M Plus temperature apps','components':components},indent=2)+'\n') +PYTHON +export REMOVE_ID=$(aws greengrassv2 create-deployment --cli-input-json file://remove-deployment.json --query deploymentId --output text) +aws greengrassv2 list-effective-deployments --core-device-thing-name "$THING_NAME" +aws greengrassv2 list-installed-components --core-device-thing-name "$THING_NAME" +``` + +Wait for this removal revision to succeed. + +## Confirming that the board has been cleaned up + +Using the recorded run-unit names and work paths: + +```bash +export FW_UNIT=`systemctl list-unit-files --type=service | grep NXPIMX8MPlus | awk '{print $1}' | grep Zephyr` +export BRIDGE_UNIT=`systemctl list-unit-files --type=service | grep NXPIMX8MPlus | awk '{print $1}' | grep Bridge` +journalctl -u "$FW_UNIT" -u "$BRIDGE_UNIT" -b --no-pager -n 100 +nxp-mcore status +systemctl is-active "$FW_UNIT" "$BRIDGE_UNIT" +``` + +You should see that the application Cortex-M7 is now **offline**, prior firmware filename restored, normal quiescence/stop messages, inactive or removed component units, and no new IoTCore JSON messages being published in the MQTT test console. + +## Additional detail: To re-enable, invoke a redeployment adding the components back into the deployment itself + +Reapply the saved `deployment.json` to re-enable both components to be listed as part of the revised deployment. Once successfully deployed, you should again see JSON temperature messages published into AWS IoTCore via the MQTT test client. + +## Additional detail: Optionally retire cloud resources + +After removal from every target, delete the two recorded private component version ARNs with `aws greengrassv2 delete-component --arn VERSION_ARN`. Remove only their versioned S3 prefixes and delete the bucket only if dedicated and empty. + +If no device still needs this path's supplemental policy and role permission: + +```bash +aws iot detach-policy --policy-name NXPIMX8MPlusExternalTemperaturePublish --target "$CERT_ARN" +aws iot delete-policy --policy-name NXPIMX8MPlusExternalTemperaturePublish +aws iam delete-role-policy --role-name "$ROLE_NAME" --policy-name NXPIMX8MPlusExternalTemperatureArtifacts +``` + +## What you have learned + +You can successfully enable and disable these two components via updated deployments. This feature provides an `on/off` management capability for the components and their associated apps (artifacts). In generalized lifecycle management of edge devices, this technique, along with updating S3 artifacts, revising component versions, and revising deployment references to component versions, are all used to manage the overall application and its lifecycle within the edge device. diff --git a/content/learning-paths/embedded-and-microcontrollers/nxp-imx8uplus-gglite-zephyr-combined-part3/deploy.md b/content/learning-paths/embedded-and-microcontrollers/nxp-imx8uplus-gglite-zephyr-combined-part3/deploy.md new file mode 100644 index 0000000000..7cc1d207ab --- /dev/null +++ b/content/learning-paths/embedded-and-microcontrollers/nxp-imx8uplus-gglite-zephyr-combined-part3/deploy.md @@ -0,0 +1,91 @@ +--- +title: "NXP FRDM i.MX 8M Plus: Deploy both components and verify temperature" +description: "Preserve the group selection and observe actual BMP280 JSON in IoT Core." +weight: 7 +layout: "learningpathall" +--- + +## Preserve the latest group deployment + +On the Ubuntu host in `$HOME/nxp-imx8uplus-temperature-part3`, retain the variables from the previous section: + +```bash +export GROUP_ARN=$(aws iot describe-thing-group --thing-group-name "$THING_GROUP" --query thingGroupArn --output text) +aws iot list-things-in-thing-group --thing-group-name "$THING_GROUP" +aws greengrassv2 list-deployments --target-arn "$GROUP_ARN" --history-filter LATEST_ONLY +``` + +Set `BASE_DEPLOYMENT_ID` to the latest deployment ID just listed: + +```bash +export BASE_DEPLOYMENT_ID=YOUR_LATEST_GROUP_DEPLOYMENT_ID +aws greengrassv2 get-deployment --deployment-id "$BASE_DEPLOYMENT_ID" \ + > previous-deployment.json +``` + +Create the deployment now: + +```bash +python3 - <<'PYTHON' +import json,os +from pathlib import Path +base=json.loads(Path('previous-deployment.json').read_text()) +assert base['targetArn']==os.environ['GROUP_ARN'] +components=base.get('components',{}).copy() +version=json.loads(Path('release.json').read_text())['version'] +components['com.arm.NXPIMX8MPlus.ZephyrExternalTemperature']={'componentVersion':version} +components['com.arm.NXPIMX8MPlus.ExternalTemperatureBridge']={'componentVersion':version,'configurationUpdate':{'merge':json.dumps({'serialDevice':'/dev/nxp-temperature'})}} +Path('deployment.json').write_text(json.dumps({'targetArn':os.environ['GROUP_ARN'],'deploymentName':'NXP FRDM i.MX 8M Plus BMP280 telemetry','components':components},indent=2)+'\n') +PYTHON +export DEPLOYMENT_ID=$(aws greengrassv2 create-deployment --cli-input-json file://deployment.json --query deploymentId --output text) +aws greengrassv2 list-effective-deployments --core-device-thing-name "$THING_NAME" +aws greengrassv2 list-installed-components --core-device-thing-name "$THING_NAME" +``` + +Wait for this deployment to succeed on this device and for both components to run. You can view the deployment progress on the AWS Console if desired. + +## Examine events on the board + +After deployment fully completes on our board, we should see that our MCU is active and that we have new device files for temperature and MCU control: + +```bash +nxp-mcore status +systemctl list-units --all --type=service --no-pager | grep -F NXPIMX8MPlus +journalctl -u ggl.core.ggdeploymentd.service -b --no-pager -n 100 +ls -l /dev/nxp-temperature /dev/nxp-mcore-control +``` + +Lets check the status on each of the services for our two apps: + +```bash +export FW_UNIT=`systemctl list-unit-files --type=service | grep NXPIMX8MPlus | awk '{print $1}' | grep Zephyr` +export BRIDGE_UNIT=`systemctl list-unit-files --type=service | grep NXPIMX8MPlus | awk '{print $1}' | grep Bridge` +export FW_WORK=$(systemctl show "$FW_UNIT" --property=WorkingDirectory --value) +export BRIDGE_WORK=$(systemctl show "$BRIDGE_UNIT" --property=WorkingDirectory --value) +journalctl -u "$FW_UNIT" -u "$BRIDGE_UNIT" -b -f +``` + +Expect FRDM Linux preflight `PASS` lines before remoteproc start, then `MCore started firmware=...` and bridge `Published sequence=... topic=nxp/imx8mplus/temperature/external` messages. Do not run `cat` on the telemetry endpoint concurrently with the bridge. Press Ctrl+C to stop journal following; the applications keep running. + +## Observe the external sensor in AWS + +In **AWS IoT Core → MQTT test client**, subscribe to `nxp/imx8mplus/temperature/external` using the same account/Region. Verify `thingName=MyNXPIMX8MPlus`, `sensor=BMP280`, advancing sequence/uptime, and plausible temperature. Gently warm the external module and observe the value change and recover. + +A deployment status and journal entry do not replace a real observed message. Complete the removal/redeployment test on the next page. + + +## Additional detail: diagnosing issues + +| Failure | Inspect | +| --- | --- | +| S3 denied | Actual UTC/time source and diagnostic error code, then device role, prefix policy, bucket/Region, boundaries and encryption | +| Offline wheel install fails | Actual board Python version and AArch64 wheels declared in the recipe | +| MCU owner refuses startup | Correct image profile, offline core, and no stale owner record | +| RPMsg endpoints missing | Resource-table patch, vring/memory agreement, mailbox, cache settings and RPMSG_TTY | +| No sensor frames | BMP280 chip/address, board-specific bus/pins, pull-ups, and peripheral ownership | +| IPC denied | Recipe operation and exact topic policy | +| Nothing in IoT Core | Certificate publish permission, endpoint/Region and subscriber permissions | + +## What you have learned + +You can deploy the two Greengrass components, verify operations, and confirm a real external temperature JSON response in AWS IoT Core. diff --git a/content/learning-paths/embedded-and-microcontrollers/nxp-imx8uplus-gglite-zephyr-combined-part3/firmware.md b/content/learning-paths/embedded-and-microcontrollers/nxp-imx8uplus-gglite-zephyr-combined-part3/firmware.md new file mode 100644 index 0000000000..47f751366c --- /dev/null +++ b/content/learning-paths/embedded-and-microcontrollers/nxp-imx8uplus-gglite-zephyr-combined-part3/firmware.md @@ -0,0 +1,112 @@ +--- +title: "NXP FRDM i.MX 8M Plus: Build and test the BMP280 temperature firmware" +description: "Compile the MCU sensor app and validate its operation manually." +weight: 4 +layout: "learningpathall" +--- + +## Build the temperature sensor MCU application ELF + +On the Ubuntu host, lets initiate a build of the temperature sensor MCU source: + +```bash +source "$HOME/nxp-imx8uplus-zephyr-venv/bin/activate" +export ZEPHYR_WORKSPACE="$HOME/nxp-imx8uplus-zephyr-workspace" +export ZEPHYR_TOOLCHAIN_VARIANT=zephyr +export ZEPHYR_SDK_INSTALL_DIR="$HOME/zephyr-sdk-0.17.4" +cd "$HOME/nxp-imx8uplus-temperature-part3" +bash setup-zephyr-sdk.sh +bash build-zephyr.sh temperature +python3 inspect-elf.py build/temperature/zephyr/zephyr.elf +"$ZEPHYR_SDK_INSTALL_DIR/arm-zephyr-eabi/bin/arm-zephyr-eabi-readelf" -h -S -l build/temperature/zephyr/zephyr.elf +``` + +## Manually run the ELF on the MCU and verify sensor connectivity + +In a SSH shell on the Ubuntu host, manually copy over the compiled elf to the i.MX8MPLUS dev board: + +```bash +scp $HOME/nxp-imx8uplus-temperature-part3/build/temperature/zephyr/zephyr.elf root@OUR_BOARD_IP_ADDRESS:./temperature-zephyr.elf +``` + +In a SSH onto our dev board, lets manually invoke the elf to confirm it is working: + +```bash +ssh root@OUR_BOARD_IP_ADDRESS +nxp-mcore load ./temperature-zephyr.elf +nxp-mcore status +``` + +You should see output similar to: + +```output +device=/sys/class/remoteproc/remoteproc0 name=imx-rproc state=running firmware=nxp-imx8uplus-gg-34be8b5189faa9e9.elf +``` + +With your access to the MCU UART DEBUG console previously setup, you should see output similar to: + +```output +*** Booting Zephyr OS build v4.3.0 *** +NXP FRDM i.MX 8M Plus: Zephyr on application MCU +External BMP280 found at I2C address 0x77 +``` + +Lastly, we can confirm that temperature JSONs are being published locally on the dev board. On the dev board, type: + +```bash +stty -F /dev/nxp-temperature raw -echo +printf 'HELLO\n' > /dev/nxp-temperature +timeout 60 cat /dev/nxp-temperature +``` + +You get approximately 60 seconds of periodic output that resembles: + +```output +{"type":"nxp.external.temperature","schema":1,"seq":14,"uptime_ms":70298,"temperature_uC":25730000} +{"type":"nxp.external.temperature","schema":1,"seq":15,"uptime_ms":75308,"temperature_uC":25570000} +{"type":"nxp.external.temperature","schema":1,"seq":16,"uptime_ms":80318,"temperature_uC":25550000} +``` + +This output indicates that the MCU has proper wiring to the BMP280 temperature sensor and that the elf is correctly reading and publishing temperature values. + +We can now stop the ELF: + +```bash +nxp-mcore stop +nxp-mcore status +``` + +Output should resemble: + +```output +device=/sys/class/remoteproc/remoteproc0 name=imx-rproc state=offline firmware=rproc-imx-rproc-fw +``` + +## Additional detail: Acquire and compensate actual temperature + +The application detects the BMP280 at `0x76` or `0x77`, verifies chip ID, resets it, reads factory `dig_T1/2/3` calibration, and triggers one forced temperature measurement approximately every five seconds. It skips pressure and uses the signed integer compensation helper tested on the host. + +The hundredths-of-a-degree result is scaled into the existing microdegree transport field. It does not imply microdegree sensor precision. A frame looks like: + +```json +{"type":"nxp.external.temperature","schema":1,"seq":12,"uptime_ms":60320,"temperature_uC":25080000} +``` + +A failed sensor read emits a diagnostic and no temperature frame. The bridge does not substitute a SoC thermal reading, a fixed value, or a Linux sensor value. The NXP FRDM i.MX 8M Plus overlay selects the physical bus described on the preparation page. + +## Additional Detail: Manage the full MCU lifecycle + +The first recipe downloads `zephyr.elf`, `firmware_manager.py` and +`check-linux.py` before installation. `install` validates and stages the ELF. +Before modifying firmware or sysfs, `run` checks FRDM Linux identity, the running +`clk-imx8mp.mcore_booted` argument, exact named reserved-memory ranges, released +UART4 and an offline M7. A failed preflight aborts the start. It then records +ownership, installs a digest-derived firmware filename, starts remoteproc and +completes the control endpoint's HELLO/READY exchange. + +On normal SIGTERM, the manager exchanges `STOP` / `QUIESCED`, waits briefly for the MCU to enter WFI, requests remoteproc stop, requires offline state, restores the previous firmware filename, and removes its installed ELF and ownership record. It leaves a safe lock inode and the runtime's own cache infrastructure. + + +## What you have learned + +You can compile the actual NXP FRDM i.MX 8M Plus BMP280 firmware and manually confirm that the firmware runs successfully on the MCU and that the BMP280 temperature sensor is reachable and connected to the firmware when it runs. diff --git a/content/learning-paths/embedded-and-microcontrollers/nxp-imx8uplus-gglite-zephyr-combined-part3/images/temperature-flow.png b/content/learning-paths/embedded-and-microcontrollers/nxp-imx8uplus-gglite-zephyr-combined-part3/images/temperature-flow.png new file mode 100644 index 0000000000..263592df30 Binary files /dev/null and b/content/learning-paths/embedded-and-microcontrollers/nxp-imx8uplus-gglite-zephyr-combined-part3/images/temperature-flow.png differ diff --git a/content/learning-paths/embedded-and-microcontrollers/nxp-imx8uplus-gglite-zephyr-combined-part3/images/temperature-flow.svg b/content/learning-paths/embedded-and-microcontrollers/nxp-imx8uplus-gglite-zephyr-combined-part3/images/temperature-flow.svg new file mode 100644 index 0000000000..c0c4550ad0 --- /dev/null +++ b/content/learning-paths/embedded-and-microcontrollers/nxp-imx8uplus-gglite-zephyr-combined-part3/images/temperature-flow.svg @@ -0,0 +1,132 @@ + + NXP FRDM i.MX 8M Plus: BMP280 temperature to AWS IoT Core + Greengrass downloads two components from S3 and runs them on Yocto Linux on Cortex-A53. Component 1 loads and stops the Zephyr firmware on Cortex-M7 through remoteproc. The BMP280 sends temperature over I2C to Zephyr, which sends calibrated JSON frames over RPMsg shared memory to Component 2, the Linux bridge. The bridge publishes through Greengrass IPC and the runtime's MQTT connection to AWS IoT Core. + + + + + + + + + + + + + + NXP FRDM i.MX 8M Plus: external temperature to the cloud + Two Greengrass components connect Zephyr sensing with an AWS IoT Core JSON topic. + + + + AWS CLOUD + + + + + + Greengrass group deployment + Recipes + component versions + Target: NXPIMX8MPlusDevices + + + + + S3 artifacts + Zephyr ELF + scripts + Bridge + offline SDK wheels + + + + AWS IoT Core + MQTT / TLS + JSON temperature messages + + + + NXP FRDM i.MX 8M Plus · i.MX 8M Plus + + CORTEX-A53 · YOCTO LINUX + + + + + + + Deployment + artifact download + + + + + COMPONENT 1 + Firmware manager + Install ELF; supervise MCU + + + + Greengrass Lite + Install / run lifecycle + IPC + device MQTT connection + + + + + + COMPONENT 2 + Linux telemetry bridge + + install / run + + + + + CORTEX-M7 + Zephyr app + Read + compensate + BMP280 temperature + + + + + + + BMP280 + External sensor module + 3.3 V · I2C 0x76 / 0x77 + + + + I2C + + + RPMsg TTY · JSON + Shared memory + mailbox + + IPC + + + Publish to IoT Core + + remoteproc + load / start / stop + + + + IoT Core topic: + nxp/imx8mplus/temperature/external + Temperature telemetry + Greengrass deployment / lifecycle + MCU firmware control + diff --git a/content/learning-paths/embedded-and-microcontrollers/nxp-imx8uplus-gglite-zephyr-combined-part3/intro.md b/content/learning-paths/embedded-and-microcontrollers/nxp-imx8uplus-gglite-zephyr-combined-part3/intro.md new file mode 100644 index 0000000000..48f2138009 --- /dev/null +++ b/content/learning-paths/embedded-and-microcontrollers/nxp-imx8uplus-gglite-zephyr-combined-part3/intro.md @@ -0,0 +1,51 @@ +--- +title: "NXP FRDM i.MX 8M Plus: Deploy sensor firmware and a cloud bridge" +description: "Read BMP280 temperature from the application MCU and convey up into AWS IoT Core." +weight: 2 +layout: "learningpathall" +--- + +## What we will build + +Use the Part 1 Yocto image on Cortex-A53 and the Part 2 Zephyr environment for Cortex-M7. + +In this learning path, we will create, register and deploy two custom AWS Greengrass components: + +| Component | Application and lifecycle | +| --- | --- | +| `com.arm.NXPIMX8MPlus.ZephyrExternalTemperature` | Downloads the ELF, manager and Linux preflight helper from S3, checks the FRDM boot/memory configuration, stages firmware, runs the application MCU, and quiesces/stops it and removes its installed copy on normal termination | +| `com.arm.NXPIMX8MPlus.ExternalTemperatureBridge` | Downloads the bridge, lifecycle script and SDK wheels from S3, installs offline, reads MCU telemetry, publishes JSON through Greengrass IPC, and removes its installed Python directory on normal termination | + +As our board is running the AWS Greengrass `Lite` variant, we will be deploying the above two components to the AWS Greengrass group `NXPIMX8MPlusDevices`. + +![NXP FRDM i.MX 8M Plus BMP280 sensing and Greengrass component flow](images/temperature-flow.png) + +JSON messages containing temperature sensor information will be published in AWS IoTCore to the topic: `nxp/imx8mplus/temperature/external`. We will connect the external BMP280 I2C module to our board using our jumper wires. + +## Additional details on our integration + +Zephyr sends JSON through OpenAMP/RPMsg shared memory and the SoC mailbox. Linux's `rpmsg-tty` driver exposes `/dev/nxp-temperature`. A separate `/dev/nxp-mcore-control` endpoint carries the quiescence handshake, so the firmware manager and bridge do not contend for one serial port. No external UART telemetry jumper is required. + +The MCU completes a sample, puts the sensor to sleep, acknowledges `STOP` with `QUIESCED`, and enters WFI. The manager then uses this platform's remoteproc stop operation. + +Nucleus Lite 2.3.0 does not provide a recipe `shutdown` lifecycle. Both components therefore run foreground processes in their Greengrass systemd units and handle normal SIGTERM cleanup. Do not detach these applications into separately enabled services. + +Here, removing or unpublishing an app from the device means revising every deployment that selects it. Deleting a cloud version or canceling a deployment does not stop its installed app. Greengrass continues to own its artifact cache and work-directory infrastructure. + +## Additional Technical References + +| Topic | Source | +| --- | --- | +| Board setup and boot | [NXP FRDM i.MX 8M Plus guide](https://www.nxp.com/document/guide/getting-started-with-frdm-imx8mplus:GS-FRDM-IMX8MPLUS) and [hardware manual](https://www.nxp.com/webapp/Download?colCode=UM12340) | +| Release and machine selection | [NXP BSP manifest](https://github.com/nxp-imx/imx-manifest/blob/07d7cd3f29a18e809f6391eea1be01103b1d6e13/imx-6.12.49-2.2.0.xml) and [machine configuration](https://github.com/nxp-imx/meta-imx/blob/1cfbbb8f9ce1d6071775ea6083b79d98597c8206/meta-imx-bsp/conf/machine/imx8mp-lpddr4-frdm.conf) | +| Kernel and remoteproc | [Linux recipe](https://github.com/nxp-imx/meta-imx/blob/1cfbbb8f9ce1d6071775ea6083b79d98597c8206/meta-imx-bsp/recipes-kernel/linux/linux-imx_6.12.bb), [driver](https://github.com/nxp-imx/linux-imx/blob/df24f9428e38740256a410b983003a478e72a7c0/drivers/remoteproc/imx_rproc.c), and [board DTS](https://github.com/nxp-imx/linux-imx/blob/df24f9428e38740256a410b983003a478e72a7c0/arch/arm64/boot/dts/freescale/imx8mp-frdm.dts) | +| Zephyr baseline and RPMsg | [FRDM MCU build profile](bundle/README.md) and [OpenAMP resource-table sample](https://github.com/zephyrproject-rtos/zephyr/tree/v4.3.0/samples/subsys/ipc/openamp_rsc_table) | +| Greengrass Lite packaging | [Pinned Walnascar recipe](https://github.com/aws4embeddedlinux/meta-aws/blob/5d73130967dce143f44fe2f80d65361f6b653c5e/recipes-iot/aws-iot-greengrass/greengrass-lite_2.3.0.bb) and [2.3.0 provisioning](https://github.com/aws-greengrass/aws-greengrass-lite/blob/v2.3.0/docs/Provisioning.md) | +| Component authoring and delivery | [Recipe reference](https://docs.aws.amazon.com/greengrass/v2/developerguide/component-recipe-reference.html), [S3 role permissions](https://docs.aws.amazon.com/greengrass/v2/developerguide/device-service-role.html), and [deployment creation](https://docs.aws.amazon.com/greengrass/v2/developerguide/create-deployments.html) | +| Cloud publishing | [MQTT IPC authorization](https://docs.aws.amazon.com/greengrass/v2/developerguide/ipc-iot-core-mqtt.html) | +| FRDM sensor header | [NXP FRDM-IMX8MPLUS schematic, sheet 21](https://www.nxp.com/downloads/en/schematics/FRDM-IMX8MPLUS-SCH-95022_B1.zip) | +| BMP280 | [Bosch datasheet](https://www.bosch-sensortec.com/media/boschsensortec/downloads/datasheets/bst-bmp280-ds001.pdf) | + +## What you have learned + +You understand how NXP FRDM i.MX 8M Plus combines the external sensor, its application MCU, and the Yocto Linux bridge using two Greengrass components for application publication and lifecycle control. \ No newline at end of file diff --git a/content/learning-paths/embedded-and-microcontrollers/nxp-imx8uplus-gglite-zephyr-combined-part3/prepare.md b/content/learning-paths/embedded-and-microcontrollers/nxp-imx8uplus-gglite-zephyr-combined-part3/prepare.md new file mode 100644 index 0000000000..c0a643f4a5 --- /dev/null +++ b/content/learning-paths/embedded-and-microcontrollers/nxp-imx8uplus-gglite-zephyr-combined-part3/prepare.md @@ -0,0 +1,64 @@ +--- +title: "NXP FRDM i.MX 8M Plus: Prepare and wire the BMP280" +description: "Verify the image/core and wire the board-specific sensor bus." +weight: 3 +layout: "learningpathall" +--- + +## Start with an offline application MCU + +On NXP FRDM i.MX 8M Plus, lets ensure our M7 is offline: + +```bash +nxp-mcore stop +nxp-mcore status +cat /etc/nxp-lp/board.json +cat /proc/cmdline +python3 /usr/libexec/nxp-lp/check-linux.py +python3 -c 'import sys; print(sys.version)' +python3 -m pip --version +``` + +Stopping an already inactive test service is harmless. Power down your board now. + +## Wire up the BMP280 with board power disconnected + +With the board powered down, connect the BMP280 as follows to our dev board: + +| BMP280 connection | NXP FRDM i.MX 8M Plus connection | +| --- | --- | +| VCC / 3V3 | J18.1 (3.3V) | +| GND | J18.6 (GND) | +| SDA / SDI | J18.3 (I2C3_SDA_3V3) | +| SCL / SCK | J18.5 (I2C3_SCL_3V3) | +| CS / CSB | J18.20 (GND) | +| SDO | J18.17 (3.3V for `0x77`) | + + +## Additional details: wiring the BMP280 sensor + +Keep CSB high from power-up to select I2C. Grounding CSB selects SPI and +disables I2C until the BMP280 is power-cycled; see +[Bosch's datasheet, section 5.1](https://www.bosch-sensortec.com/media/boschsensortec/downloads/datasheets/bst-bmp280-ds001.pdf#page=27). +After a power cycle, reload a manual MCU test. If loading reports a stale owner +record, use the updated manager's recovery procedure in `MCU-RECOVERY.md` in +the source bundle. Successful readings travel over RPMsg; the debug console +prints sensor discovery once and reports acquisition failures. + +## Extract the complete Part 3 MCU temperature sources + +On the Ubuntu host, download [the NXP FRDM i.MX 8M Plus Part 3 MCU temperature source bundle](../temperature-source.zip) to your HOME directory: + +```bash +mkdir -p "$HOME/nxp-imx8uplus-temperature-part3" +unzip $HOME/temperature-source.zip -d "$HOME/nxp-imx8uplus-temperature-part3" +cd "$HOME/nxp-imx8uplus-temperature-part3" +``` + +This source zip file includes the MCU source, FRDM clock override, both resource-table patches, build/ELF inspection helpers, Linux preflight, manager, bridge, recipe generator, upload script, and host checks. + +Next, we will build the temperature application. + +## What you have learned + +You can verify an offline Cortex-M7, wire the BMP280 to the verified NXP FRDM i.MX 8M Plus bus signals, and prepare to build our temperature application. diff --git a/content/learning-paths/embedded-and-microcontrollers/nxp-imx8uplus-gglite-zephyr-combined-part3/publish.md b/content/learning-paths/embedded-and-microcontrollers/nxp-imx8uplus-gglite-zephyr-combined-part3/publish.md new file mode 100644 index 0000000000..878f0ee37f --- /dev/null +++ b/content/learning-paths/embedded-and-microcontrollers/nxp-imx8uplus-gglite-zephyr-combined-part3/publish.md @@ -0,0 +1,148 @@ +--- +title: "NXP FRDM i.MX 8M Plus: Publish both S3-backed custom components" +description: "Grant artifact and MQTT permissions and register immutable component versions." +weight: 6 +layout: "learningpathall" +--- + +## Confirm the environment + +Run this page on the Ubuntu host, in the source workspace. Retain the actual AWS Region and existing device role alias from Part 1: + +```bash +cd "$HOME/nxp-imx8uplus-temperature-part3" +export AWS_REGION=us-east-1 +export AWS_DEFAULT_REGION="$AWS_REGION" +export THING_NAME=MyNXPIMX8MPlus +export THING_GROUP=NXPIMX8MPlusDevices +export ACCOUNT_ID=$(aws sts get-caller-identity --query Account --output text) +export IOT_ROLE_ALIAS=YOUR_EXISTING_ROLE_ALIAS +export ROLE_ARN=$(aws iot describe-role-alias --role-alias "$IOT_ROLE_ALIAS" \ + --query roleAliasDescription.roleArn --output text) +export ROLE_NAME=${ROLE_ARN##*/} +export ARTIFACT_BUCKET="nxp-imx8uplus-temperature-${ACCOUNT_ID}-${AWS_REGION}-YOUR_UNIQUE_SUFFIX" +export ARTIFACT_PREFIX=nxp-imx8uplus-temperature +``` + +Update/customize the IOT_ROLE_ALIAS (`YOUR_EXISTING_ROLE_ALIAS`) and the bucket suffix (`YOUR_UNIQUE_SUFFIX`), before running commands. Use lowercase letters, digits, and hyphens in the bucket name. + +## Create a S3 artifact bucket + +Lets create our S3 bucket for our component artifacts: + +```bash +aws s3api create-bucket --bucket "$ARTIFACT_BUCKET" --region "$AWS_REGION" +aws s3api put-public-access-block --bucket "$ARTIFACT_BUCKET" \ + --public-access-block-configuration \ + BlockPublicAcls=true,IgnorePublicAcls=true,BlockPublicPolicy=true,RestrictPublicBuckets=true +aws s3api put-bucket-encryption --bucket "$ARTIFACT_BUCKET" \ + --server-side-encryption-configuration \ + '{"Rules":[{"ApplyServerSideEncryptionByDefault":{"SSEAlgorithm":"AES256"}}]}' +``` + +## Generate both complete recipes + +Lets build our component recipe JSON files: + +```bash +python3 tools/make_recipes.py --bucket "$ARTIFACT_BUCKET" --prefix "$ARTIFACT_PREFIX" --region "$AWS_REGION" +python3 -m json.tool recipes/com.arm.NXPIMX8MPlus.ZephyrExternalTemperature.json +python3 -m json.tool recipes/com.arm.NXPIMX8MPlus.ExternalTemperatureBridge.json +``` + +The generator enumerates the actual staged files, including both wheel filenames, and creates the version in `release.json` (currently `1.0.1`) of exactly two generic components. Both manifests select `linux`, `aarch64`, and `aws_nucleus_lite`. Every artifact has an explicit private `s3://` URI. There is no dependency on the Java nucleus, Java CLI component, or a third custom service. + +## Grant artifact downloads to the existing device role in AWS IAM + +Part 1's inline Hello World needed no S3 permission. Add the following narrowly scoped policy to its **existing token-exchange IAM role**, following [AWS's artifact-access guidance](https://docs.aws.amazon.com/greengrass/v2/developerguide/device-service-role.html#device-service-role-access-s3-bucket): + +```bash +python3 -m json.tool artifact-access.json +aws iam put-role-policy --role-name "$ROLE_NAME" \ + --policy-name NXPIMX8MPlusExternalTemperatureArtifacts \ + --policy-document file://artifact-access.json +``` + +Use a fresh inline-policy name if that name is already used for another purpose. Preserve the role trust, permissions boundary, role alias, and Part 1 policies. A boundary or explicit deny must also permit these reads. The role does not need S3 write access; the workstation identity performs uploads and component registration. + +## Grant the device certificate access to the exact MQTT topic to be used + +There are three separate authorization checks: device-role S3 reads, component IPC publish authorization, and certificate IoT publish authorization. The recipe generator supplies the IPC permission. Add a supplemental certificate policy for the topic: + +```bash +python3 - <<'PYTHON' +import json, os +from pathlib import Path +arn = ('arn:aws:iot:' + os.environ['AWS_REGION'] + ':' + os.environ['ACCOUNT_ID'] + + ':topic/nxp/imx8mplus/temperature/external') +Path('temperature-publish.json').write_text(json.dumps({ + 'Version': '2012-10-17', 'Statement': [ + {'Effect': 'Allow', 'Action': 'iot:Publish', 'Resource': arn} + ] +}, indent=2) + '\n') +PYTHON +aws iot list-thing-principals --thing-name "$THING_NAME" +``` + +Set `CERT_ARN` to the active certificate actually used by this board, from the returned principals (replace `YOUR_DEVICE_CERTIFICATE_ARN` with the devices certificate's ARN. You can find that in the AWS Console when examining our device `thing` within AWS IoT Core portion of the dashboard). With the ARN set for `CERT_ARN`, lets type: + +```bash +export CERT_ARN=YOUR_DEVICE_CERTIFICATE_ARN +aws iot create-policy --policy-name NXPIMX8MPlusExternalTemperaturePublish \ + --policy-document file://temperature-publish.json +aws iot attach-policy --policy-name NXPIMX8MPlusExternalTemperaturePublish --target "$CERT_ARN" +``` + +If that supplemental policy already exists, inspect its default version and reuse it only if its contents match. Leave the original connection-kit policy attached. + +## Upload the artifacts into S3, then create the components + +Lets upload our artifacts into S3. Once done, we can create the two components: + +```bash +python3 tools/upload.py --plan artifact-plan.json +aws s3 ls "s3://$ARTIFACT_BUCKET/$ARTIFACT_PREFIX/" --recursive +python3 tools/check_artifact_access.py --plan artifact-plan.json \ + --role-alias "$IOT_ROLE_ALIAS" && +aws greengrassv2 create-component-version \ + --inline-recipe fileb://recipes/com.arm.NXPIMX8MPlus.ZephyrExternalTemperature.json && +aws greengrassv2 create-component-version \ + --inline-recipe fileb://recipes/com.arm.NXPIMX8MPlus.ExternalTemperatureBridge.json +``` + +Keep the returned version ARNs. + +{{% notice NOTE %}} +Never overwrite S3 objects behind a published component version: registration records artifact integrity information, and devices may already cache the old bytes. For an update, change only `release.json` to an unused version, use new versioned S3 keys, restage into a clean staging tree, regenerate, upload, and publish a new component version. The old version and its artifacts remain available for rollback. +{{% /notice %}} + +## Additional details: Diagnosing an artifact 403 before changing lifecycle scripts + +Artifacts download before install/run scripts execute. The pinned Lite runtime +signs S3 requests using its configured awsRegion, so the bucket must be in that +Region. Copy the exact iotRoleAlias from this board's effective configuration; +a workstation IAM user or a similarly named role is not the device identity. +The generated policy grants reads for these two component prefixes across +versions, retaining rollback access. It does not make the bucket public. + +The read-only preflight requires the workstation to call GetBucketLocation, +HeadObject, DescribeRoleAlias and SimulatePrincipalPolicy. It checks all seven +objects, server SHA256, Region and simulated role reads. This is not an on-device +credential/signing test and does not rule out bucket/SCP/VPC explicit denies, +KMS policy issues or a wrong board clock. SSE-KMS requires separate verification. + +For an already published version, inspect its actual S3 URIs first. If the URIs +are correct, repair the existing token-exchange role's read policy and retry +the deployment; that alone does not require a new component version. If the +URIs/bytes are wrong, publish an unused version with fresh keys. Do not replace +objects behind 1.0.0 or delete the working Hello World deployment. + +If these workstation checks pass but the board still gets 403, use the +read-only `tools/diagnose_s3.py` procedure in ARTIFACT-DELIVERY.md. It uses the +board certificate and fresh credentials, reports the caller ARN and S3 error +code, and excludes credentials from output. It is a comparison against the +supplied configuration, not a dump of the daemon's cached credentials. + +## What you have learned + +You can create S3 buckets, generate both AWS Greengrass component recipes, upload our built component artifacts, and create the components. diff --git a/content/learning-paths/embedded-and-microcontrollers/nxp-imx8uplus-gglite-zephyr-combined-part3/temperature-source.zip b/content/learning-paths/embedded-and-microcontrollers/nxp-imx8uplus-gglite-zephyr-combined-part3/temperature-source.zip new file mode 100644 index 0000000000..e8248d17b6 Binary files /dev/null and b/content/learning-paths/embedded-and-microcontrollers/nxp-imx8uplus-gglite-zephyr-combined-part3/temperature-source.zip differ diff --git a/content/learning-paths/embedded-and-microcontrollers/nxp-imx8uplus-yocto-gglite-part1/.python-version b/content/learning-paths/embedded-and-microcontrollers/nxp-imx8uplus-yocto-gglite-part1/.python-version new file mode 100644 index 0000000000..a616492698 --- /dev/null +++ b/content/learning-paths/embedded-and-microcontrollers/nxp-imx8uplus-yocto-gglite-part1/.python-version @@ -0,0 +1 @@ +2.7.18 diff --git a/content/learning-paths/embedded-and-microcontrollers/nxp-imx8uplus-yocto-gglite-part1/_index.md b/content/learning-paths/embedded-and-microcontrollers/nxp-imx8uplus-yocto-gglite-part1/_index.md new file mode 100644 index 0000000000..dd2e786d50 --- /dev/null +++ b/content/learning-paths/embedded-and-microcontrollers/nxp-imx8uplus-yocto-gglite-part1/_index.md @@ -0,0 +1,44 @@ +--- +title: "Part 1: NXP FRDM i.MX 8M Plus: Build Yocto and deploy a Greengrass Lite Hello World" +draft: true +cascade: + draft: true +description: "Build a board-specific NXP Yocto image, provision its identity, and deploy Hello World through a thing group." +minutes_to_complete: 120 +who_is_this_for: Embedded Linux developers connecting an NXP application processor and MCU to AWS IoT Greengrass. +learning_objectives: + - "Build the imx8mp-lpddr4-frdm image with Greengrass Lite and MCU integration" + - "Provision a unique AWS IoTCore/Greengrass identity for NXP FRDM i.MX 8M Plus" + - "Publish and deploy a board-specific Hello World component" +prerequisites: + - "NXP FRDM i.MX 8M Plus with an appropriate power supply, microSD card and reader, wired Ethernet, and its debug USB cable" + - An Ubuntu 22.04 or 24.04 host on x86_64 (amd64) or arm64 (aarch64) with 32 GB RAM and 300–500 GB free space on a Linux filesystem + - AWS CLI v2 and an account permitted to manage IoT identities, Greengrass deployments, and component artifacts +author: Doug Anson +generate_summary_faq: true +rerun_summary: false +rerun_faqs: false +skilllevels: Advanced +subjects: Embedded Linux +armips: + - Cortex-A +operatingsystems: + - Linux +tools_software_languages: + - Yocto Project + - AWS IoT Greengrass + - Python +further_reading: + - resource: + title: "NXP FRDM i.MX 8M Plus Part 2 \u2014 Zephyr alongside Linux" + link: /learning-paths/embedded-and-microcontrollers/nxp-imx8uplus-yocto-zephyr-part2/ + type: learningpath + - resource: + title: "NXP FRDM i.MX 8M Plus Part 3 \u2014 BMP280 telemetry and cloud components" + link: /learning-paths/embedded-and-microcontrollers/nxp-imx8uplus-gglite-zephyr-combined-part3/ + type: learningpath +### FIXED, DO NOT MODIFY +weight: 1 +layout: "learningpathall" +learning_path_main_page: "yes" +--- diff --git a/content/learning-paths/embedded-and-microcontrollers/nxp-imx8uplus-yocto-gglite-part1/_next-steps.md b/content/learning-paths/embedded-and-microcontrollers/nxp-imx8uplus-yocto-gglite-part1/_next-steps.md new file mode 100644 index 0000000000..e20dfa6d43 --- /dev/null +++ b/content/learning-paths/embedded-and-microcontrollers/nxp-imx8uplus-yocto-gglite-part1/_next-steps.md @@ -0,0 +1,8 @@ +--- +# ================================================================================ +# FIXED, DO NOT MODIFY THIS FILE +# ================================================================================ +weight: 21 +title: "Next Steps" +layout: "learningpathall" +--- diff --git a/content/learning-paths/embedded-and-microcontrollers/nxp-imx8uplus-yocto-gglite-part1/build.md b/content/learning-paths/embedded-and-microcontrollers/nxp-imx8uplus-yocto-gglite-part1/build.md new file mode 100644 index 0000000000..beaf538ce0 --- /dev/null +++ b/content/learning-paths/embedded-and-microcontrollers/nxp-imx8uplus-yocto-gglite-part1/build.md @@ -0,0 +1,102 @@ +--- +title: "NXP FRDM i.MX 8M Plus: Build the Yocto development image" +description: "Use the NXP manifest and board-specific kernel and runtime layer." +weight: 3 +layout: "learningpathall" +--- + +## Prepare the Linux build host + +Use Ubuntu 22.04 or 24.04 (or a compatible Ubuntu-based distribution) on +**x86_64/amd64 or arm64/aarch64**, with a native Linux filesystem. The Yocto build script +detects the CPU architecture, installs native apt dependencies and selects the +matching SDKMACHINE for the optional Linux SDK. BitBake selects its native build +tools; MACHINE continues to select the FRDM board. + +Lets get started by setting up the build scripts on our Ubuntu host: + +```bash +mkdir -p "$HOME/nxp-imx8uplus-yocto-bundle" +unzip yocto-build.zip -d "$HOME/nxp-imx8uplus-yocto-bundle" +cd "$HOME/nxp-imx8uplus-yocto-bundle" +bash build-yocto.sh --help +``` + +Read NXP's EULA from the BSP before setting `ACCEPT_FSL_EULA=1`. Set that variable only if you accept the terms. It is required for NXP's firmware packages. + +```bash +export ACCEPT_FSL_EULA=1 +WORKDIR="$HOME/yocto-nxp-imx8uplus" JOBS=4 bash build-yocto.sh --install-deps --configure-only --no-sdk +``` + +The script selects machine `imx8mp-lpddr4-frdm` explicitly in its configuration block, uses the dedicated `build-frdm` directory, sources NXP's `imx-setup-release.sh`, and adds the supplied `meta-nxp-lp` layer and pinned `meta-aws`. It preserves configuration outside its own marked block. Existing `build/` configurations are left untouched; the same `WORKDIR` and downloaded sources can be reused. `LP_BUILD_DIR` can select another single directory name when needed. + +NXP's first-time setup removes `imx95-19x19-verdin.conf` and `include/imx95-evk.inc` from `sources/meta-freescale`, because it supplies replacements in `meta-imx`. This happens for all three board builds. The script recognizes only these unstaged deletions at the pinned release, verifies that the replacements are unchanged, and preserves the removals if sync restores the files. Other edits, staged deletions, and untracked files still stop the build before sync. Keep `bsp-checkouts.py` beside `build-yocto.sh` when updating an extracted bundle. + +Configure-only runs parsing and image dependency-graph generation. It does not compile yocto. Inspect the recorded manifest and graphs: + +```bash +cat "$HOME/yocto-nxp-imx8uplus/meta-aws.lock" +ls "$HOME/yocto-nxp-imx8uplus/validation/image" +``` + +We are now ready to build yocto. + +## Build the Yocto image and optional SDK + +Initiate the build on the Ubuntu host. You can adjust the JOBS parameter to suit how many CPUs you have on your build host: + +```bash +WORKDIR="$HOME/yocto-nxp-imx8uplus" JOBS=4 bash build-yocto.sh --no-sdk +ls -lh "$HOME/yocto-nxp-imx8uplus/build-frdm/tmp/deploy/images/imx8mp-lpddr4-frdm/"*.wic* +``` + +## Additional build script details: Included AWS Greengrass Lite runtime details + +The image installs `packagegroup-nxp-lp-greengrass`, which requires +`greengrass-lite`, `libcgroup`, `sudo` and CA certificates. The pinned +`greengrass-lite_2.3.0.bb` recipe builds every core daemon, CLI, recipe runner +and token-exchange service; its library dependencies are resolved through the +recipe and package manager. No separate `ggtesd` recipe is required. + +The learning-path append explicitly enables systemd unit installation. Before +compilation, `verify-greengrass.py` checks the selected recipe/version/source, +all core units and required build/runtime dependencies. The completed-image +hook then checks the actual rootfs: all 12 Greengrass executables, 19 core units, +version marker, support files and service/component accounts. It also checks +the deployed package manifest. Missing files fail the image build. + +The build script publishes build reports in WORKDIR: + +```text +validation/greengrass-config.json +validation/greengrass-image.json +``` + +The image audit is deployed beside the WIC as +`nxp-lp-dev-image-MACHINE.greengrass.json` and is tied to the package manifest's +SHA256. Keep these reports with the image. `--configure-only` checks metadata +and dependency graphs; its result does not prove that binaries were installed. +See `bundle/GREENGRASS-RUNTIME.md` for the audited component list. + +## Additional build script details: Understanding the board integration + +The kernel append uses NXP's `DELTA_KERNEL_DEFCONFIG` step, which runs after its recipe replaces `.config`. It checks remoteproc and RPMsg options after configuration. A board-specific patch updates the machine's original DTB, so the stock boot flow selects the modified board tree using the FRDM board DTB. + +For M7 use, obtain the updated bundle whose reserved-memory node names are +`vdev0vring0@55000000`, `vdev0vring1@55008000`, and `vdev0buffer@55400000`. +The original `vring@...` names were not matched by Linux remoteproc. Rebuild and +boot the corrected `imx8mp-frdm.dtb`; rebuilding Zephyr alone is insufficient. +The corrected U-Boot defaults select `imx8mp-frdm.dtb` and run `prepare_mcore` +before the BSP boot path. Verify the actual Linux model and command line after boot. See Part 2's `HANG-FIX.md` +and run its read-only `check-linux.py` before starting M7. + +The image includes `nxp-mcore`, `nxp-provision-greengrass`, `/etc/nxp-lp/board.json`, and stable RPMsg aliases. Greengrass services remain disabled until the first provisioning step, preventing an empty configuration database from being seeded before credentials exist. + +If packaging fails with `got *at() syscall for unknown directory, fd 4` and `tar: ... Cannot mkdir: Bad address`, update the complete bundle at its existing location and rerun the build command with the same `WORKDIR`. Newer host `tar` security updates use `openat2`, which the BSP's pinned `pseudo` cannot track. The bundled layer backports the [upstream syscall fix](https://git.yoctoproject.org/pseudo/commit/?id=472c8977e0238e5a1ed4d29d7c41de699646ceff) and its header follow-up. The script builds the patched `pseudo-native` before building the image. BitBake tracks the patch changes and rebuilds affected tasks; keep your BSP edits, downloads, and shared-state cache. + +If BitBake fails, fix the first reported error and reuse the same work directory. A namespace denial is a build-host policy issue; configure it with the administrator instead of running BitBake as root. + +## What you have learned + +You have learned how to select the imx8mp-lpddr4-frdm NXP BSP, generate its dependency graph, and build an image with Greengrass and MCU support. You can locate the actual WIC/SDK artifacts and distinguish source/configuration checks from a completed build. diff --git a/content/learning-paths/embedded-and-microcontrollers/nxp-imx8uplus-yocto-gglite-part1/component.md b/content/learning-paths/embedded-and-microcontrollers/nxp-imx8uplus-yocto-gglite-part1/component.md new file mode 100644 index 0000000000..bb1f7b357e --- /dev/null +++ b/content/learning-paths/embedded-and-microcontrollers/nxp-imx8uplus-yocto-gglite-part1/component.md @@ -0,0 +1,71 @@ +--- +title: "NXP FRDM i.MX 8M Plus: Publish the Hello World component" +description: "Publish and deploy the NXP FRDM i.MX 8M Plus Hello World component." +weight: 6 +layout: "learningpathall" +--- + +## Prepare the component workspace + +Run this page's commands on the Ubuntu host, keeping the AWS account, Region, and variables from the provisioning page. Create a workspace outside the device-credential directory: + +```bash +mkdir -p "$HOME/nxp-imx8uplus-hello-world" +cd "$HOME/nxp-imx8uplus-hello-world" +``` + +## Create the component recipe + +Save the following JSON as `recipe.json` in the workspace. The component defines its application directly in the manifest's `run` lifecycle. It prints `Hello from Greengrass Lite on NXP FRDM i.MX 8M Plus!` every 60 seconds. The empty `Artifacts` list means you do not need an S3 bucket, a separate shell script, or artifact download permissions. + +```json +{ + "RecipeFormatVersion": "2020-01-25", + "ComponentName": "com.arm.NXPIMX8MPlus.HelloGreengrassLiteWorld", + "ComponentVersion": "1.0.1", + "ComponentType": "aws.greengrass.generic", + "ComponentDescription": "A simple test component for Greengrass Lite", + "ComponentPublisher": "Arm", + "Manifests": [ + { + "Platform": { + "os": "linux", + "runtime": "aws_nucleus_lite", + "architecture": "aarch64" + }, + "Lifecycle": { + "run": "while true; do echo 'Hello from Greengrass Lite on NXP FRDM i.MX 8M Plus!'; sleep 60; done" + }, + "Artifacts": [] + } + ], + "Lifecycle": {} +} +``` + +The platform selector targets Linux on `aarch64` with the `aws_nucleus_lite` runtime. The recipe has no dependency on the Java nucleus or its CLI component. + +Validate the JSON before publishing: + +```bash +python3 -m json.tool recipe.json +``` + +The command displays the formatted recipe. If it reports a parsing error, correct the JSON before continuing. + +## Publish the component + +Register version `1.0.1` as a private component in your account, then list its published versions: + +```bash +aws greengrassv2 create-component-version \ + --inline-recipe fileb://recipe.json +aws greengrassv2 list-component-versions \ + --arn "arn:aws:greengrass:$AWS_REGION:$(aws sts get-caller-identity --query Account --output text):components:com.arm.NXPIMX8MPlus.HelloGreengrassLiteWorld" +``` + +Confirm, back at the AWS Console, that version `1.0.1` appears under **Greengrass devices > Components > My components** for `com.arm.NXPIMX8MPlus.HelloGreengrassLiteWorld`. Component versions are immutable: publish a new version when you change the recipe. If this version already exists, use the existing version only if its recipe matches this example. + +## What you have learned + +You can create and publish the trivial `Hello World` Greengrass component. The component utilizes JSON structure to define its content and lifecycle. In the next section, we'll deploy the component down to our device via Greengrass deployments. diff --git a/content/learning-paths/embedded-and-microcontrollers/nxp-imx8uplus-yocto-gglite-part1/deployment.md b/content/learning-paths/embedded-and-microcontrollers/nxp-imx8uplus-yocto-gglite-part1/deployment.md new file mode 100644 index 0000000000..f7b74dff59 --- /dev/null +++ b/content/learning-paths/embedded-and-microcontrollers/nxp-imx8uplus-yocto-gglite-part1/deployment.md @@ -0,0 +1,147 @@ +--- +title: "NXP FRDM i.MX 8M Plus: Deploy and verify Hello World" +description: "Publish and deploy the NXP FRDM i.MX 8M Plus Hello World component." +weight: 7 +layout: "learningpathall" +--- + +## Deploy the Hello World custom component to our board + +On the Ubuntu host, confirm group membership and retrieve the device group's ARN: + +```bash +aws iot list-things-in-thing-group --thing-group-name "$THING_GROUP" +export GROUP_ARN=$(aws iot describe-thing-group \ + --thing-group-name "$THING_GROUP" --query thingGroupArn --output text) +aws greengrassv2 list-deployments --target-arn "$GROUP_ARN" +``` + +With AWS Greengrass `Lite`, we publish components to their associated device group. Only AWS Greengrass `Classic` allows publication of components to individual devices. + +The member list must include `MyNXPIMX8MPlus` - our devices IoTCore name. This tutorial expects a dedicated group with no previous deployment. If a deployment already exists, inspect it before continuing. A new deployment to the same target replaces that target's previous component selection, so retain any components that you still need. See [Create deployments](https://docs.aws.amazon.com/greengrass/v2/developerguide/create-deployments.html). + +Lets create a Greengrass deployment document targeting the group ARN as our device utilizes Greengrass `Lite`: + +```bash +python3 - <<'PYTHON' +import json +import os +from pathlib import Path + +request = { + "targetArn": os.environ["GROUP_ARN"], + "deploymentName": "NXPIMX8MPlus Hello World group deployment", + "components": { + "com.arm.NXPIMX8MPlus.HelloGreengrassLiteWorld": { + "componentVersion": "1.0.1" + } + } +} +Path("deployment.json").write_text(json.dumps(request, indent=2) + "\n") +PYTHON +export DEPLOYMENT_ID=$(aws greengrassv2 create-deployment \ + --cli-input-json file://deployment.json --query deploymentId --output text) +printf '%s\n' "$DEPLOYMENT_ID" +``` + +Keep this deployment ID. The deployment intentionally contains only the custom component; it uses the Lite runtime already installed in the image. + +You can perform the same operation in the console by choosing **Greengrass devices > Deployments > Create**, selecting **Thing group**, choosing `NXPIMX8MPlusDevices` - our device group's name, and adding version `1.0.1` of `com.arm.NXPIMX8MPlus.HelloGreengrassLiteWorld`. Review the target and component version before choosing **Deploy**. Use either the CLI or console workflow once. + +## Check delivery to this device + +Inspect both the deployment and its effective status on the board: + +```bash +aws greengrassv2 get-deployment --deployment-id "$DEPLOYMENT_ID" +aws greengrassv2 list-effective-deployments \ + --core-device-thing-name "$THING_NAME" +aws greengrassv2 list-installed-components \ + --core-device-thing-name "$THING_NAME" +``` + +The group deployment can remain `ACTIVE` to serve group members. That status alone does not prove installation on a particular board. Wait for the matching deployment ID to report `SUCCEEDED` in the effective deployments response, and for component version `1.0.1` to appear as running in the installed-components response. Cloud status updates can lag behind device execution. + +## Observe the application on NXP FRDM i.MX 8M Plus + +On the board via SSH, inspect deployment logs and find the component's systemd service: + +```bash +journalctl -u ggl.core.ggdeploymentd.service -b --no-pager -n 100 +systemctl list-units --all --type=service | grep -F HelloGreengrassLiteWorld | awk '{print $1}' +export COMPONENT_UNIT=`systemctl list-units --all --type=service | grep -F HelloGreengrassLiteWorld | awk '{print $1}'` +``` + +Use the exact unit name reported by `systemctl` to inspect the component. Replace `COMPONENT_UNIT` with that name: + +```bash +systemctl status ${COMPONENT_UNIT} +``` + +You should see that the service is running normally. Next, type: + +```bash +journalctl -u ${COMPONENT_UNIT} -b -f +``` + +For this command (which will be ongoing...) the output should contain this (with additional ones added every 60 seconds): + +```output +Hello from Greengrass Lite on NXP FRDM i.MX 8M Plus! +Hello from Greengrass Lite on NXP FRDM i.MX 8M Plus! +``` + +The journal adds timestamps and service prefixes. Observe at least two messages about 60 seconds apart, then press **Ctrl+C** to stop following the journal. The component continues running. + +Successful completion requires all three observations: + + - Our device, as an AWS IoTCore thing, belongs to the targeted AWS Greengrass group: NXPIMX8MPlusDevices + - This deployment succeeds on the device, and + - The application's repeated message appears in the device journal. + + +This proves our AWS Greengrass group deployment succeeded. + +## Troubleshoot a failed deployment + +| Symptom | What to check | +| --- | --- | +| No effective deployment | Same account and Region, correct group ARN, thing membership, and IoT connectivity | +| Authorization or token-exchange failure | Active certificate, attached IoT policy, role alias, and IAM role trust | +| No matching manifest | `uname -m` is `aarch64`, Linux is running, and the manifest selects `aws_nucleus_lite` | +| Component exits immediately | Component unit journal and the inline `run` lifecycle command | +| Edited YAML has no effect | Existing configuration database takes precedence; use supported configuration updates rather than resetting an established device | + +For service-level faults, inspect `systemctl --failed` and the `ggl.core.iotcored.service` and `ggl.core.ggdeploymentd.service` journals. Correct the reported cause before retrying; do not create another identity to work around an authorization error. + +## Optional: remove the test application + +If you are continuing to Part 2, keep the board provisioned and Greengrass running. You can keep the Hello World component deployed for the later verification. + +To stop the application through the same group target, revise the group's deployment to omit the Hello World component. This is accomplished on the Ubuntu host: + +```bash +python3 - <<'PYTHON' +import json +import os +from pathlib import Path + +Path("update-deployment.json").write_text(json.dumps({ + "targetArn": os.environ["GROUP_ARN"], + "deploymentName": "Remove NXPIMX8MPlus Hello World test", + "components": {} +}, indent=2) + "\n") +PYTHON +export DEPLOYMENT_ID=$(aws greengrassv2 create-deployment \ + --cli-input-json file://update-deployment.json --query deploymentId --output text) +printf '%s\n' "$DEPLOYMENT_ID" +``` + +Wait for this revision to succeed and confirm the application stops. If you added other components to the group deployment, retain them in the component selection. Canceling a deployment is not an uninstall operation. + + +Continue with [Part 2: Zephyr on NXP FRDM i.MX 8M Plus](/learning-paths/embedded-and-microcontrollers/nxp-imx8uplus-yocto-zephyr-part2/). + +## What you have learned + +You can publish AWS Greengrass custom components, like our Hello World component, to the AWS IoT things belonging to a specific AWS Greengrass group. You can inspect both the device and cloud status, as well as remove the test component through revised deployment publication. diff --git a/content/learning-paths/embedded-and-microcontrollers/nxp-imx8uplus-yocto-gglite-part1/intro.md b/content/learning-paths/embedded-and-microcontrollers/nxp-imx8uplus-yocto-gglite-part1/intro.md new file mode 100644 index 0000000000..b63658063b --- /dev/null +++ b/content/learning-paths/embedded-and-microcontrollers/nxp-imx8uplus-yocto-gglite-part1/intro.md @@ -0,0 +1,45 @@ +--- +title: "NXP FRDM i.MX 8M Plus: Build a connected edge device" +description: "Introduction: the board, resources used, and three-part workflow objectives." +weight: 2 +layout: "learningpathall" +--- + +## Three part series + +This three-part series connects an embedded Linux processor, a Zephyr MCU, and AWS IoTCore present in the **NXP FRDM i.MX 8M Plus** device. Part 1 builds and boots Yocto Linux running on its Cortex-A53, provisions Greengrass Lite, and deploys a simple Hello World component to the device via Greengrass. Part 2 adds a custom Zephyr heartbeat on the devices' Cortex-M7 MCU. Part 3 connects a BMP280 sensor, deploys both a Zephyr BMP280 reader application on the MCU as well as a Yocto-based Linux-to-IoT-Core bridge as two custom AWS Greengrass components. With the two custom components deployed in part 3 the temperature values, read in Zephyr, are conveyed through the bridge in Yocto up to AWS IoTCore where they are published as JSON-based messages in IoTCore. + +| Resources Used | Details | +| --- | --- | +| Yocto machine name | `imx8mp-lpddr4-frdm` | +| BSP | NXP LF6.12.49_2.2.0, Yocto 5.2 Walnascar | +| Linux | NXP 6.12.49, pinned source revision | +| AWS Greengrass Runtime | Greengrass nucleus lite 2.3.0 from the pinned Walnascar meta-aws layer | +| MCU | Cortex-A53 / Cortex-M7 | +| AWS IoTCore device name / group | `MyNXPIMX8MPlus` / `NXPIMX8MPlusDevices` | + +Allow several additional hours for a first uncached Yocto build. The image retains development login settings and is intended for a controlled development network. + +## Part 1 - Building Yocto: Use the supplied build bundle + +Download [the NXP FRDM i.MX 8M Plus yocto build bundle](../yocto-build.zip), extract it to a fixed Linux filesystem path, and keep the local layer with the script. The script uses the official NXP release manifest and this board's actual machine configuration. It adds Greengrass, Python, MCU tools, RPMsg TTY support, and explicit peripheral ownership for the later parts. + +These are source-level adaptations with local checks. The build, device journal, sensor response, and repeatable remove/redeploy checks in the following sections establish acceptance on your hardware. Downloadable bundles include the exact revisions and limits in `AUDIT.md`. + +## Technical References + +| Topic | Source | +| --- | --- | +| Board setup and boot | [NXP FRDM i.MX 8M Plus guide](https://www.nxp.com/document/guide/getting-started-with-frdm-imx8mplus:GS-FRDM-IMX8MPLUS) and [hardware manual](https://www.nxp.com/webapp/Download?colCode=UM12340) | +| Release and machine selection | [NXP BSP manifest](https://github.com/nxp-imx/imx-manifest/blob/07d7cd3f29a18e809f6391eea1be01103b1d6e13/imx-6.12.49-2.2.0.xml) and [machine configuration](https://github.com/nxp-imx/meta-imx/blob/1cfbbb8f9ce1d6071775ea6083b79d98597c8206/meta-imx-bsp/conf/machine/imx8mp-lpddr4-frdm.conf) | +| Kernel and remoteproc | [Linux recipe](https://github.com/nxp-imx/meta-imx/blob/1cfbbb8f9ce1d6071775ea6083b79d98597c8206/meta-imx-bsp/recipes-kernel/linux/linux-imx_6.12.bb), [driver](https://github.com/nxp-imx/linux-imx/blob/df24f9428e38740256a410b983003a478e72a7c0/drivers/remoteproc/imx_rproc.c), and [board DTS](https://github.com/nxp-imx/linux-imx/blob/df24f9428e38740256a410b983003a478e72a7c0/arch/arm64/boot/dts/freescale/imx8mp-frdm.dts) | +| Zephyr baseline and RPMsg | [FRDM MCU build profile](../nxp-imx8uplus-yocto-zephyr-part2/bundle/README.md) and [OpenAMP resource-table sample](https://github.com/zephyrproject-rtos/zephyr/tree/v4.3.0/samples/subsys/ipc/openamp_rsc_table) | +| Greengrass Lite packaging | [Pinned Walnascar recipe](https://github.com/aws4embeddedlinux/meta-aws/blob/5d73130967dce143f44fe2f80d65361f6b653c5e/recipes-iot/aws-iot-greengrass/greengrass-lite_2.3.0.bb) and [2.3.0 provisioning](https://github.com/aws-greengrass/aws-greengrass-lite/blob/v2.3.0/docs/Provisioning.md) | +| Component authoring and delivery | [Recipe reference](https://docs.aws.amazon.com/greengrass/v2/developerguide/component-recipe-reference.html), [S3 role permissions](https://docs.aws.amazon.com/greengrass/v2/developerguide/device-service-role.html), and [deployment creation](https://docs.aws.amazon.com/greengrass/v2/developerguide/create-deployments.html) | +| Cloud publishing | [MQTT IPC authorization](https://docs.aws.amazon.com/greengrass/v2/developerguide/ipc-iot-core-mqtt.html) | +| FRDM sensor header | [NXP FRDM-IMX8MPLUS schematic, sheet 21](https://www.nxp.com/downloads/en/schematics/FRDM-IMX8MPLUS-SCH-95022_B1.zip) | +| BMP280 | [Bosch datasheet](https://www.bosch-sensortec.com/media/boschsensortec/downloads/datasheets/bst-bmp280-ds001.pdf) | + +## What you have learned + +You understand how NXP FRDM i.MX 8M Plus, its NXP BSP machine, and its AWS identity fit together and are used in these 3 part series. You can follow the build path: Yocto → Hello World → MCU heartbeat app → managed sensor telemetry progression into AWS IoTCore using the above platform-specific resources. diff --git a/content/learning-paths/embedded-and-microcontrollers/nxp-imx8uplus-yocto-gglite-part1/provision.md b/content/learning-paths/embedded-and-microcontrollers/nxp-imx8uplus-yocto-gglite-part1/provision.md new file mode 100644 index 0000000000..50bac9feb2 --- /dev/null +++ b/content/learning-paths/embedded-and-microcontrollers/nxp-imx8uplus-yocto-gglite-part1/provision.md @@ -0,0 +1,288 @@ +--- +title: "NXP FRDM i.MX 8M Plus Dev Board : Provision Greengrass Lite" +description: "Initialize this board with a unique certificate and its existing NXP runtime." +weight: 5 +layout: "learningpathall" +--- + +## Create our board's AWS IoTCore/Greengrass identity + +On the Ubuntu host via web browser, log into the AWS console and use the one account and Region throughout this board's series. In **AWS IoT Core → Greengrass devices → Core devices → Set up core device**, select **Nucleus Lite**, create `MyNXPIMX8MPlus`, and use the dedicated thing group `NXPIMX8MPlusDevices`. Select `Set up a device with your own custom build` and press `Create thing` to create the new device in AWS IoTCore. Next, download the connection kit to your Ubuntu host. Our board and its Yocto image already has the Greengrass Lite package installed and ready to provision. + +```bash +export AWS_REGION=us-east-1 +export THING_NAME=MyNXPIMX8MPlus +export THING_GROUP=NXPIMX8MPlusDevices +``` + +## Upload the connection kit to the NXP FRDM i.MX 8M Plus Dev Board + +First create a our target directory on our board. SSH into our board: + +```bash +ssh root@OUR_BOARD_IP_ADDRESS +mkdir $HOME/gg-provision +``` + +From the Ubuntu host connected to your imx8plus dev board, invoke a scp session to copy the connection kit to the imx8plus dev board: + +```bash +scp MyNXPIMX8MPlus-connectionKit.zip root@OUR_BOARD_IP_ADDRESS:./gg-provision +``` + +{{% notice Important Note %}} + +If your AWS account is restricted such that you get an error when pressing the **Create thing** button above, you may need to manually create your entire connection kit manually via the AWS CLI. If this is the case then + +## Optional - only if your organization requires a pre-approved role or uses permissions boundary + +Most users can use the role created by the connection kit and do not need to configure a permissions boundary. If your administrator requires a pre-approved role, keep its boundary and follow the [manual provisioning guide](https://github.com/aws-greengrass/aws-greengrass-lite/blob/v2.3.0/docs/Provisioning.md#manual-provisioning-by-creating-a-thing), reusing that role instead of creating one. + +For a device-specific alias, point it to the approved role with this command, replacing both placeholders: + +```bash +aws iot update-role-alias --role-alias YOUR_ROLE_ALIAS --role-arn YOUR_APPROVED_ROLE_ARN +``` + +Use `create-role-alias` with the same arguments if the alias does not exist. Your administrator must confirm the role's trust and certificate-policy permissions. Pass the alias **name** as `YOUR_ROLE_ALIAS` to the board's provisioning helper. After manual provisioning, continue with [Prepare the credentials](#prepare-the-credentials). + +## Prepare the credentials + +On your workstation, keep the connection kit or manually downloaded credentials in a private directory outside any source checkout. Extract the kit if you used one, and identify the device certificate, private key, and Amazon Root CA. Save copies with these filenames: `device.pem.crt`, `private.pem.key`, and `AmazonRootCA1.pem`. Do not confuse the device certificate with the CA certificate or public key. + +Protect the key and transfer these three files to the board. Run from the directory containing those files: + +```bash +chmod 600 private.pem.key +scp device.pem.crt private.pem.key AmazonRootCA1.pem \ + root@OUR_BOARD_IP_ADDRESS:./gg-provision/ +``` + +AWS CLI credentials stay on the administrative workstation. The board authenticates with its device private key and certificate. + +The endpoints must match your recorded device settings. If you provisioned manually and the thing group does not exist, create it: + +```bash +aws iot create-thing-group --thing-group-name "$THING_GROUP" +``` + +The group list must contain `NXPIMX8MPlusDevices`. If the thing is not a member, add it: + +```bash +aws iot add-thing-to-thing-group --thing-name "$THING_NAME" \ + --thing-group-name "$THING_GROUP" +``` + +The command produces no output on success. Confirm membership before continuing: + +```bash +aws iot list-thing-groups-for-thing --thing-name "$THING_NAME" +``` + +Lastly, lets get our iot data endpoint and iot credential endpoint values for our specific account. Back on the Ubuntu host type: + +```bash +aws iot describe-endpoint --endpoint-type iot:Data-ATS +aws iot describe-endpoint --endpoint-type iot:CredentialProvider +``` + +Record the full `endpointAddress` from each command. It will be used in the next step. + +## Create the configuration yaml file + +Lastly, we need to create the config file for our credentials bundle. Create a file `config.yaml` with the following contents (replacing YOUR_IOT_DATA_ENDPOINT and YOUR_IOT_CRED_ENDPOINT with your actual endpoint url components from the previous command above). You may also need to update the `awsRegion` to reflect the region you wish to use: + +```yaml +--- +system: + certificateFilePath: "{{config_dir}}/device.pem.crt" + privateKeyPath: "{{config_dir}}/private.pem.key" + rootCaPath: "{{config_dir}}/AmazonRootCA1.pem" + thingName: "MyNXPIMX8MPlus" +services: + {{nucleus_component}}: + componentType: "NUCLEUS" + configuration: + awsRegion: "us-east-1" + iotRoleAlias: "GreengrassV2TokenExchangeCoreDeviceRoleAlias" + iotDataEndpoint: "YOUR_IOT_DATA_ENDPOINT-ats.iot.us-east-1.amazonaws.com" + iotCredEndpoint: "YOUR_IOT_CRED_ENDPOINT.credentials.iot.us-east-1.amazonaws.com" +``` + +Save and copy this file up with our other created key files to your imx8plus dev board from your Ubuntu host: + +```bash +scp config.yaml root@OUR_BOARD_IP_ADDRESS:/root/gg-provision/ +``` + +On your imx8plus dev board via a SSH shell confirm that you have the following files created: + +```bash +cd ~/gg-provision +ls -al +``` + +Your output should be: + +```output +-rw-r--r-- 1 root root 1188 Oct 21 15:36 AmazonRootCA1.pem +-rw-r--r-- 1 root root 528 Oct 21 15:36 config.yaml +-rw-r--r-- 1 root root 1220 Oct 21 15:36 device.pem.crt +-rw-r--r-- 1 root root 1675 Oct 21 15:36 private.pem.key +``` + +Please continue with the next section editing the `config.yaml` in this directory on your imx8plus dev board file per instructions below by skipping to the `Prepare the credentials config file` step below. +{{% /notice %}} + +## Prepare the credentials config file + +From the Ubuntu host connected to your imx8plus dev board, open a SSH session: + +```bash +ssh root@OUR_BOARD_IP_ADDRESS +``` + +Unzip the contents of the connection kit (zipped and not already placed there manually): + +```bash +cd $HOME/gg-provision +unzip $HOME/MyNXPIMX8MPlus-connectionKit.zip +``` + +Examine the `config.yaml` file: + +```bash +cat ./config.yaml +``` + +The contents of the `config.yaml` file should look like this: + +```yaml +--- +system: + certificateFilePath: "{{config_dir}}/device.pem.crt" + privateKeyPath: "{{config_dir}}/private.pem.key" + rootCaPath: "{{config_dir}}/AmazonRootCA1.pem" + thingName: "MyNXPIMX8MPlus" +services: + {{nucleus_component}}: + componentType: "NUCLEUS" + configuration: + awsRegion: "us-east-1" + iotRoleAlias: "GreengrassV2TokenExchangeCoreDeviceRoleAlias" + iotDataEndpoint: "YOUR_IOT_DATA_ENDPOINT-ats.iot.us-east-1.amazonaws.com" + iotCredEndpoint: "YOUR_IOT_CRED_ENDPOINT.credentials.iot.us-east-1.amazonaws.com" +``` + +Replace `{{config_dir}}` with `/etc/greengrass` and `{{nucleus_component}}` with `aws.greengrass.NucleusLite`: + +```yaml +--- +system: + certificateFilePath: "/etc/greengrass/device.pem.crt" + privateKeyPath: "/etc/greengrass/private.pem.key" + rootCaPath: "/etc/greengrass/AmazonRootCA1.pem" + thingName: "MyNXPIMX8MPlus" +services: + aws.greengrass.NucleusLite: + componentType: "NUCLEUS" + configuration: + awsRegion: "us-east-1" + iotRoleAlias: "GreengrassV2TokenExchangeCoreDeviceRoleAlias" + iotDataEndpoint: "YOUR_IOT_DATA_ENDPOINT-ats.iot.us-east-1.amazonaws.com" + iotCredEndpoint: "YOUR_IOT_CRED_ENDPOINT.credentials.iot.us-east-1.amazonaws.com" +``` + +Save the updated `config.yaml` file. + +## Finailize configuration of AWS IoT Greengrass + +Continuing with the SSH session into the imx8plus dev board, copy all contents from our updated connection kit to the greengrass config directory already setup on your imx8plus dev board: + +```bash +cd $HOME/gg-provision +cp * /etc/greengrass +rm /etc/greengrass/*.zip +chmod 640 /etc/greengrass/*key +chmod 640 /etc/greengrass/*pem +chmod 640 /etc/greengrass/*crt +chown -R ggcore:ggcore /etc/greengrass +ls -al /etc/greengrass +``` + +The expected contents of `/etc/greengrass` should be: + +```output +root@imx8plus dev board:~/gg-provision# ls -al /etc/greengrass +total 28 +drwxr-xr-x 3 ggcore ggcore 4096 Oct 22 19:32 . +drwxr-xr-x 48 root root 4096 Oct 22 19:34 .. +-rw-r----- 1 ggcore ggcore 1188 Oct 22 19:35 AmazonRootCA1.pem +drwxr-xr-x 2 ggcore ggcore 4096 Mar 9 2018 config.d +-rw-r--r-- 1 ggcore ggcore 540 Oct 22 19:35 config.yaml +-rw-r----- 1 ggcore ggcore 1220 Oct 22 19:35 device.pem.crt +-rw-r----- 1 ggcore ggcore 1675 Oct 22 19:35 private.pem.key +root@imx8plus dev board:~/gg-provision# +``` + +Your imx8plus dev board's AWS IoT Greengrass configuration is now complete! Restart the greengrass services on the imx8plus dev board: + +```bash +python3 /usr/libexec/nxp-lp/check-greengrass.py +gg_units="$(python3 /usr/libexec/nxp-lp/check-greengrass.py --units)" && + systemctl add-wants greengrass-lite.target $gg_units && + systemctl enable greengrass-lite.target && + systemctl restart greengrass-lite.target +systemctl status --with-dependencies greengrass-lite.target +``` + +Your imx8plus dev board's greengrass service should now be operational. + + +## Additional details: The Greengrass services + +The pinned image uses Greengrass Lite **2.3.0**. Token exchange service is +`ggl.core.tesd.service` (`tesd`), and fleet status service is +`ggl.core.gg-fleet-statusd.service` (`gg-fleet-statusd`). + +The image deliberately leaves services disabled until credentials exist. The +commands above validate all 12 executables and 19 core units, attach every core +service/socket to the target, then start it. Restarting an empty target alone +does not activate its disabled members. The provisioning helper performs the +same complete-runtime check and activation when used instead of manual setup. + +## Verify the imx8plus dev board greengrass operational status + +On the board, inspect service health and connection logs: + +```bash +systemctl status --with-dependencies greengrass-lite.target +systemctl --failed +journalctl -u ggl.core.iotcored.service -u ggl.core.ggdeploymentd.service -b --no-pager +``` + +The core services should be running without repeated certificate, authorization, or endpoint errors. On the Ubuntu host, query the registered core device: + +```bash +aws greengrassv2 get-core-device --core-device-thing-name "$THING_NAME" +``` + +Your output should resemble this (may or may not be actual json depending on how you have the aws CLI configured on your Ubuntu host): + +```output +{ + "coreDeviceThingName": "MyNXPIMX8MPlus", + "coreVersion": "2.3.0", + "platform": "linux", + "architecture": "aarch64", + "status": "HEALTHY", + "lastStatusUpdateTimestamp": 1792697816.549, + "tags": {} +} +``` + +Wait for the device to appear under **Greengrass devices > Core devices** and report healthy connectivity. If it does not, check clock synchronization, outbound connectivity, certificate activation, IoT policy attachment, and Region consistency. An IoT thing's existence alone does not prove the Greengrass runtime connected. + +## What you have accomplished + +The board has a unique AWS IoTCore identity and connects as a Greengrass core device. Next, we will publish a simple Hello World Greengrass custom component for the device to run. diff --git a/content/learning-paths/embedded-and-microcontrollers/nxp-imx8uplus-yocto-gglite-part1/setup.md b/content/learning-paths/embedded-and-microcontrollers/nxp-imx8uplus-yocto-gglite-part1/setup.md new file mode 100644 index 0000000000..8c6af7dc2d --- /dev/null +++ b/content/learning-paths/embedded-and-microcontrollers/nxp-imx8uplus-yocto-gglite-part1/setup.md @@ -0,0 +1,133 @@ +--- +title: "NXP FRDM i.MX 8M Plus: Boot and connect the board" +description: "Write the image and verify Ethernet, SSH, clock, and application-core ownership." +weight: 4 +layout: "learningpathall" +--- + +## Write our Yocto image to our microSD card + +On the Linux host with the microSD card reader attached, identify the whole microSD device: + +```bash +lsblk -o NAME,SIZE,MODEL,MOUNTPOINTS +``` + +Writing an image erases that device. Check its model and capacity, unmount its partitions, and replace both placeholders (path to youir wic image and which /dev/sdX represents your microSD card) below with the actual WIC artifact and whole device. We'll keep the factory eMMC image untouched and available as a recovery option on our board. + +```bash +sudo apt install -y zstd +zstd -d --keep /path/to/nxp-lp-dev-image.rootfs.wic.zst +sudo dd if=/path/to/nxp-lp-dev-image.rootfs.wic of=/dev/sdX bs=4M conv=fsync status=progress +sync +``` +On your developer board, locate the `SW5` boot configuration switch (it should be set to 0010 by default - boot from eMMC). Update the switch to `0011` to boot from the SD card insead of the eMMC storage. + +Additionally, connect the USB debug port to your Ubuntu host. + +The NXP FRDM i.MX 8M Plus [board guide](https://www.nxp.com/design/design-center/development-boards-and-designs/FRDM-IMX8MPLUS) and [manual](https://www.nxp.com/docs/en/quick-reference-guide/FRDMIMX8MPLUSQSG.pdf) identify the power, debug, Ethernet, and boot-switch connectors. Use Ethernet networking and the boot-switch positions specified for this board revision. + +Apply power to the board to begin its booting from the microSD card. + +## Log into the newly booted board and set credentials + +On the board's Linux console via the USB serial connection, login. Then set the root password: + +```bash +passwd +``` + +Next, lets find what IP address our board has: + +```bash +ip route | grep default | awk '{print $9}' +``` + +Save off the IP address (we'll replace OUR_BOARD_IP_ADDRESS with this IP address below) + +From your Ubuntu host, lets open a SSH shell into our board (with IP address): + +```bash +ssh root@OUR_BOARD_IP_ADDRESS +``` + +Inside our SSH shell, lets get some information about our Yocto image running on our board: + +```bash +uname -m +ip -br address +ip route +command -v nxp-mcore +command -v nxp-provision-greengrass +python3 /usr/libexec/nxp-lp/check-greengrass.py +cat /etc/nxp-lp/board.json +nxp-mcore status +``` + +Expect `aarch64`, the correct NXP FRDM i.MX 8M Plus profile, and an offline application Cortex-M7. + +If the core is attached, detached, or already running, identify the existing firmware owner and correct the boot configuration. Never overwrite or stop a different management core. The manager selects the device-tree compatible `fsl,imx8mn-cm7`, not a fixed remoteproc index. + +## Verify outbound connectivity + +Using the SSH shell into our board, lets check Internet connectivity: + +```bash +timedatectl set-ntp true +systemctl status ntpd.service --no-pager -l +ntpq -pn +ntpq -c rv +date -u +timedatectl status +getent hosts amazontrust.com +curl -I https://www.amazontrust.com/repository/AmazonRootCA1.pem +python3 -c 'import sys; print(sys.version)' +``` + +This image uses `ntpd`. Correct time is required for AWS IoT Greengrass. + +Verify the gateway, DNS, UTC time, HTTPS access, and Python version. The Walnascar image normally uses Python 3.13; record the actual major/minor for Part 3 wheel selection. Part 1's Greengrass services are intentionally not enabled yet. Do not start them until you install the device provisioning information (next section). + +## Verify the FRDM bootloader and M7 preparation + +Reboot your board and stop at U-Boot prompt by pressing `Enter`. Confirm the required configuration: + +```bash +printenv bootcmd fdtfile prepare_mcore +``` + +Output should look like this: + +```output +bootcmd=run prepare_mcore; run bsp_bootcmd +fdtfile=imx8mp-frdm.dtb +prepare_mcore=setenv mcore_clk clk-imx8mp.mcore_booted +``` + +If the output is different, then lets configure it: + +```bash +setenv fdtfile imx8mp-frdm.dtb +setenv bootcmd 'run prepare_mcore; run bsp_bootcmd' +saveenv +``` + +Then reconfirm the configuration: + +```bash +printenv bootcmd fdtfile prepare_mcore +``` + +Output should look like this: + +```output +bootcmd=run prepare_mcore; run bsp_bootcmd +fdtfile=imx8mp-frdm.dtb +prepare_mcore=setenv mcore_clk clk-imx8mp.mcore_booted +``` + +Your board is now ready for the next steps! + +## What you have learned + +You have learned how to flash and boot the correct NXP FRDM i.MX 8M Plus image, establish SSH over Ethernet, and verify the board profile, application MCU state, and outbound connection before provisioning. diff --git a/content/learning-paths/embedded-and-microcontrollers/nxp-imx8uplus-yocto-gglite-part1/yocto-build.zip b/content/learning-paths/embedded-and-microcontrollers/nxp-imx8uplus-yocto-gglite-part1/yocto-build.zip new file mode 100644 index 0000000000..4f3b7ac62b Binary files /dev/null and b/content/learning-paths/embedded-and-microcontrollers/nxp-imx8uplus-yocto-gglite-part1/yocto-build.zip differ diff --git a/content/learning-paths/embedded-and-microcontrollers/nxp-imx8uplus-yocto-zephyr-part2/.python-version b/content/learning-paths/embedded-and-microcontrollers/nxp-imx8uplus-yocto-zephyr-part2/.python-version new file mode 100644 index 0000000000..a616492698 --- /dev/null +++ b/content/learning-paths/embedded-and-microcontrollers/nxp-imx8uplus-yocto-zephyr-part2/.python-version @@ -0,0 +1 @@ +2.7.18 diff --git a/content/learning-paths/embedded-and-microcontrollers/nxp-imx8uplus-yocto-zephyr-part2/_index.md b/content/learning-paths/embedded-and-microcontrollers/nxp-imx8uplus-yocto-zephyr-part2/_index.md new file mode 100644 index 0000000000..80a19c6686 --- /dev/null +++ b/content/learning-paths/embedded-and-microcontrollers/nxp-imx8uplus-yocto-zephyr-part2/_index.md @@ -0,0 +1,50 @@ +--- +title: "Part 2: NXP FRDM i.MX 8M Plus \u2014 Run a Zephyr heartbeat alongside Yocto Linux" +draft: true +cascade: + draft: true +description: "Build a board-specific Zephyr application and manage it through Linux remoteproc while Greengrass keeps running." +minutes_to_complete: 90 +who_is_this_for: Embedded Linux developers connecting an NXP application processor and MCU to AWS IoT Greengrass. +learning_objectives: + - "Build Zephyr for the application Cortex-M7" + - "Observe an MCU heartbeat alongside Linux" + - "Quiesce and stop the application core through remoteproc" +prerequisites: + - "NXP FRDM i.MX 8M Plus with an appropriate power supply, microSD card and reader, wired Ethernet, and its debug USB cable" + - An Ubuntu 22.04 or 24.04 host on x86_64 (amd64) or arm64 (aarch64) with 32 GB RAM and 300–500 GB free space on a Linux filesystem + - AWS CLI v2 and an account permitted to manage IoT identities, Greengrass deployments, and component artifacts + - "Complete Part 1 for this same board; retain its image, identity and thing group" + - Python 3.12 or newer, west, CMake, Ninja, and Zephyr SDK 0.17.4 on the Linux development host +author: Doug Anson +generate_summary_faq: true +rerun_summary: false +rerun_faqs: false +skilllevels: Advanced +subjects: Embedded Linux +armips: + - Cortex-A + - Cortex-M +operatingsystems: + - Linux + - RTOS +tools_software_languages: + - Yocto Project + - AWS IoT Greengrass + - Python + - Zephyr + - C +further_reading: + - resource: + title: "NXP FRDM i.MX 8M Plus Part 1 \u2014 Yocto and Greengrass" + link: /learning-paths/embedded-and-microcontrollers/nxp-imx8uplus-yocto-gglite-part1/ + type: learningpath + - resource: + title: "NXP FRDM i.MX 8M Plus Part 3 \u2014 BMP280 telemetry and cloud components" + link: /learning-paths/embedded-and-microcontrollers/nxp-imx8uplus-gglite-zephyr-combined-part3/ + type: learningpath +### FIXED, DO NOT MODIFY +weight: 1 +layout: "learningpathall" +learning_path_main_page: "yes" +--- diff --git a/content/learning-paths/embedded-and-microcontrollers/nxp-imx8uplus-yocto-zephyr-part2/_next-steps.md b/content/learning-paths/embedded-and-microcontrollers/nxp-imx8uplus-yocto-zephyr-part2/_next-steps.md new file mode 100644 index 0000000000..e20dfa6d43 --- /dev/null +++ b/content/learning-paths/embedded-and-microcontrollers/nxp-imx8uplus-yocto-zephyr-part2/_next-steps.md @@ -0,0 +1,8 @@ +--- +# ================================================================================ +# FIXED, DO NOT MODIFY THIS FILE +# ================================================================================ +weight: 21 +title: "Next Steps" +layout: "learningpathall" +--- diff --git a/content/learning-paths/embedded-and-microcontrollers/nxp-imx8uplus-yocto-zephyr-part2/build.md b/content/learning-paths/embedded-and-microcontrollers/nxp-imx8uplus-yocto-zephyr-part2/build.md new file mode 100644 index 0000000000..0ccaba1274 --- /dev/null +++ b/content/learning-paths/embedded-and-microcontrollers/nxp-imx8uplus-yocto-zephyr-part2/build.md @@ -0,0 +1,106 @@ +--- +title: "NXP FRDM i.MX 8M Plus: Build the Zephyr heartbeat" +description: "Compile the supplied board-specific MCU firmware." +weight: 4 +layout: "learningpathall" +--- + +## Build preparation + +Ubuntu hosts may be either **x86_64/amd64 or arm64/aarch64**. Install native host +packages and Python 3.12+ for that Ubuntu release. West automatically selects +the matching SDK host archive; arm-zephyr-eabi remains the MCU compiler target. +After extracting the source bundle, `bash setup-zephyr-sdk.sh` installs or +checks SDK 0.17.4. Keep SDKs and virtual environments local to each host; an +incompatible existing SDK is preserved and reported before compilation. + + +For these MCU builds, the following native Ubuntu packages work on either host +architecture. Apt chooses amd64 or arm64 packages automatically; the Zephyr SDK +supplies the MCU cross-compiler, so host gcc-multilib/g++-multilib are unnecessary. +Ubuntu 24.04 supplies Python 3.12; on Ubuntu 22.04 provide Python 3.12+ and its +matching venv support before creating the virtual environment below. + +```bash +sudo apt-get update +sudo apt-get install -y git cmake ninja-build gperf ccache device-tree-compiler python3-dev python3-pip python3-venv xz-utils file make gcc g++ wget +``` + +## Prepare a dedicated west workspace + +On the Ubuntu host, use Python 3.12 or newer, CMake, Ninja, and the host dependencies from the [Zephyr getting-started guide](https://docs.zephyrproject.org/4.3.0/develop/getting_started/index.html). Ubuntu 24.04 provides Python 3.12 and its matching venv package. + +First, lets create a venv for python3.12: + +```bash +python3.12 -m venv "$HOME/nxp-imx8uplus-zephyr-venv" +source "$HOME/nxp-imx8uplus-zephyr-venv/bin/activate" +``` + +Confirm that we now have a venv with python3.12: + +```bash +python3 --version +``` + +You should see some version of 3.12 reported. Next lets install west: + +```bash +python3 -m pip install west +export PATH="$HOME/.local/bin:$PATH" +``` + +Now, lets initialize our zephyr build workspace: + +```bash +python3 -m west init -m https://github.com/zephyrproject-rtos/zephyr --mr v4.3.0 "$HOME/nxp-imx8uplus-zephyr-workspace" +cd "$HOME/nxp-imx8uplus-zephyr-workspace" +python3 -m west update +python3 -m west zephyr-export +python3 -m pip install -r zephyr/scripts/requirements.txt +``` + +## Build the heartbeat + +Download and extract [this board's MCU source bundle](../mcu-source.zip). Then: + +```bash +cd "$HOME" +mkdir -p "$HOME/nxp-imx8uplus-mcu" +unzip $HOME/mcu-source.zip -d "$HOME/nxp-imx8uplus-mcu" +cd "$HOME/nxp-imx8uplus-mcu" +source "$HOME/nxp-imx8uplus-zephyr-venv/bin/activate" +export ZEPHYR_WORKSPACE="$HOME/nxp-imx8uplus-zephyr-workspace" +export ZEPHYR_TOOLCHAIN_VARIANT=zephyr +export ZEPHYR_SDK_INSTALL_DIR="$HOME/zephyr-sdk-0.17.4" +bash setup-zephyr-sdk.sh +bash build-zephyr.sh heartbeat +``` + +## Inspect the heartbeat MCU ELF artifact + +The helper automatically checks the TCM segments, reset vectors, RPMsg resource table, and strong FRDM clock override: + +```bash +python3 inspect-elf.py build/heartbeat/zephyr/zephyr.elf +"$ZEPHYR_SDK_INSTALL_DIR/arm-zephyr-eabi/bin/arm-zephyr-eabi-readelf" -h -S -l build/heartbeat/zephyr/zephyr.elf +``` + +You should see a little-endian 32-bit Arm ELF, a resource table with the RPMsg virtio device, and loadable sections appropriate to this MCU's TCM mapping. + +## Additional details: about the heartbeat ELF structure + +`src/frdm_clock.c` overrides the upstream weak `SOC_ClockInit()` so M7 startup leaves the live Linux AHB/M7 clock roots and system PLLs alone. `firmware/prj.conf` and `profile.conf` select the mailbox, shared-memory, and cache handling for NXP FRDM i.MX 8M Plus. The heartbeat mode does not acquire the BMP280. The Part 1 device tree and this source bundle agree on shared memory beginning at `0x55000000` and the fixed resource table at MCU address `0x550ff000`. + +The original bundle compiled without a `.resource_table` section because its no-copy patch made the template unused. The corrected helper explicitly retains it, and `inspect-elf.py` rejects artifacts missing it. + +The reference heartbeat ELF was subsequently reported running on the user's +FRDM board with the corrected Part 1 image: Linux remained responsive, the +manager completed its control handshake, and heartbeat sequences advanced +continuously. See [the board result](../validation/BOARD-RESULT.md). A new build +still needs its own execution and stop/restart checks. The temperature profile +has been cross-compiled; physical BMP280 and AWS tests remain outstanding. + +## What you have learned + +You can build the NXP FRDM i.MX 8M Plus heartbeat with the pinned toolchain, apply the Linux-owned resource-table policy, and inspect the ELF before transferring it to the application core. diff --git a/content/learning-paths/embedded-and-microcontrollers/nxp-imx8uplus-yocto-zephyr-part2/intro.md b/content/learning-paths/embedded-and-microcontrollers/nxp-imx8uplus-yocto-zephyr-part2/intro.md new file mode 100644 index 0000000000..2f117eac81 --- /dev/null +++ b/content/learning-paths/embedded-and-microcontrollers/nxp-imx8uplus-yocto-zephyr-part2/intro.md @@ -0,0 +1,46 @@ +--- +title: "NXP FRDM i.MX 8M Plus: Run Zephyr alongside Linux" +description: "Understand the board-specific application MCU and remoteproc lifecycle." +weight: 2 +layout: "learningpathall" +--- + +## Keep Linux and add a real-time application + +Retain the Part 1 image, Greengrass identity, and Hello World deployment on NXP FRDM i.MX 8M Plus. Build Zephyr for the application Cortex-M7 while Linux stays on Cortex-A53. The firmware prints a numbered heartbeat on the MCU console and also exposes an RPMsg TTY to Linux. + +| Resource | Details | +| --- | --- | +| Yocto machine | `imx8mp-lpddr4-frdm` | +| Zephyr target | `imx8mp_evk/mimx8ml8/m7` | +| Runtime control | Linux remoteproc compatible `fsl,imx8mn-cm7` | +| Host versions | Zephyr v4.3.0 / SDK 0.17.4 | +| Telemetry / control | `/dev/nxp-temperature` / `/dev/nxp-mcore-control` | + +The FRDM profile reuses Zephyr v4.3.0's `imx8mp_evk/mimx8ml8/m7` target for i.MX 8M Plus SoC support. This is an upstream software identifier; the physical board is FRDM-IMX8MPLUS. Keep the supplied application overlay and resource-table patch with that target. + +## Understand startup and shutdown + +The application announces two `rpmsg-tty` endpoints. Fixed remote addresses distinguish telemetry (`0x400`) and lifecycle control (`0x401`); the image's udev rules create stable aliases. The MCU owns its resources; Linux loads the ELF and manages the application's power state. + +The resource-table patch prevents Zephyr from copying its original table over the vring addresses that Linux has already populated. It is specific to the Linux-managed firmware in this series. Keep a dedicated west workspace for these apps. + +Before stopping the core, the foreground Linux manager requests `STOP` over the separate control endpoint and requires `QUIESCED`. The MCU enters WFI after completing its work. The NXP driver then performs the platform's SMC/SCMI stop. The source and image use this NXP SoC's mailbox and memory map. + +## Additional Technical References + +| Topic | Source | +| --- | --- | +| Board setup and boot | [NXP FRDM i.MX 8M Plus guide](https://www.nxp.com/document/guide/getting-started-with-frdm-imx8mplus:GS-FRDM-IMX8MPLUS) and [hardware manual](https://www.nxp.com/webapp/Download?colCode=UM12340) | +| Release and machine selection | [NXP BSP manifest](https://github.com/nxp-imx/imx-manifest/blob/07d7cd3f29a18e809f6391eea1be01103b1d6e13/imx-6.12.49-2.2.0.xml) and [machine configuration](https://github.com/nxp-imx/meta-imx/blob/1cfbbb8f9ce1d6071775ea6083b79d98597c8206/meta-imx-bsp/conf/machine/imx8mp-lpddr4-frdm.conf) | +| Kernel and remoteproc | [Linux recipe](https://github.com/nxp-imx/meta-imx/blob/1cfbbb8f9ce1d6071775ea6083b79d98597c8206/meta-imx-bsp/recipes-kernel/linux/linux-imx_6.12.bb), [driver](https://github.com/nxp-imx/linux-imx/blob/df24f9428e38740256a410b983003a478e72a7c0/drivers/remoteproc/imx_rproc.c), and [board DTS](https://github.com/nxp-imx/linux-imx/blob/df24f9428e38740256a410b983003a478e72a7c0/arch/arm64/boot/dts/freescale/imx8mp-frdm.dts) | +| Zephyr baseline and RPMsg | [FRDM MCU build profile](bundle/README.md) and [OpenAMP resource-table sample](https://github.com/zephyrproject-rtos/zephyr/tree/v4.3.0/samples/subsys/ipc/openamp_rsc_table) | +| Greengrass Lite packaging | [Pinned Walnascar recipe](https://github.com/aws4embeddedlinux/meta-aws/blob/5d73130967dce143f44fe2f80d65361f6b653c5e/recipes-iot/aws-iot-greengrass/greengrass-lite_2.3.0.bb) and [2.3.0 provisioning](https://github.com/aws-greengrass/aws-greengrass-lite/blob/v2.3.0/docs/Provisioning.md) | +| Component authoring and delivery | [Recipe reference](https://docs.aws.amazon.com/greengrass/v2/developerguide/component-recipe-reference.html), [S3 role permissions](https://docs.aws.amazon.com/greengrass/v2/developerguide/device-service-role.html), and [deployment creation](https://docs.aws.amazon.com/greengrass/v2/developerguide/create-deployments.html) | +| Cloud publishing | [MQTT IPC authorization](https://docs.aws.amazon.com/greengrass/v2/developerguide/ipc-iot-core-mqtt.html) | +| FRDM sensor header | [NXP FRDM-IMX8MPLUS schematic, sheet 21](https://www.nxp.com/downloads/en/schematics/FRDM-IMX8MPLUS-SCH-95022_B1.zip) | +| BMP280 | [Bosch datasheet](https://www.bosch-sensortec.com/media/boschsensortec/downloads/datasheets/bst-bmp280-ds001.pdf) | + +## What you have learned + +You understand how NXP FRDM i.MX 8M Plus runs Linux and Zephyr together, which MCU and board target to select, and how the RPMsg control channel makes a normal stop repeatable. \ No newline at end of file diff --git a/content/learning-paths/embedded-and-microcontrollers/nxp-imx8uplus-yocto-zephyr-part2/load.md b/content/learning-paths/embedded-and-microcontrollers/nxp-imx8uplus-yocto-zephyr-part2/load.md new file mode 100644 index 0000000000..b017728de7 --- /dev/null +++ b/content/learning-paths/embedded-and-microcontrollers/nxp-imx8uplus-yocto-zephyr-part2/load.md @@ -0,0 +1,70 @@ +--- +title: "NXP FRDM i.MX 8M Plus: Load and stop the MCU heartbeat" +description: "Manually load and stop the Zephyr based heartbeat app on the MCU." +weight: 5 +layout: "learningpathall" +--- + +## Transfer the unstripped ELF + +From the Ubuntu build host: + +```bash +cd "$HOME/nxp-imx8uplus-mcu" +scp build/heartbeat/zephyr/zephyr.elf root@OUR_BOARD_IP_ADDRESS:/root/nxp-imx8uplus-heartbeat.elf +scp components/firmware_manager.py root@OUR_BOARD_IP_ADDRESS:/root/nxp-firmware-manager.py +scp check-linux.py root@OUR_BOARD_IP_ADDRESS:/root/check-linux.py +ssh root@OUR_BOARD_IP_ADDRESS +``` + +Copy `check-linux.py` from the extracted source bundle to `/root/check-linux.py` on the board. Complete the FRDM boot preparation from the previous page before loading. On the board as root: + +```bash +nxp-mcore status +install -m 0644 /root/nxp-firmware-manager.py /usr/libexec/nxp-lp/firmware_manager.py +install -m 0644 /root/nxp-check-linux.py /usr/libexec/nxp-lp/check-linux.py +nxp-mcore load /root/nxp-imx8uplus-heartbeat.elf +journalctl -u nxp-mcore-test.service -b -f +``` + +The helper creates a transient `nxp-mcore-test.service` running the same foreground manager that Part 3 packages. It requires an offline application Cortex-M7, validates the ELF header, records ownership, installs a unique firmware filename, starts remoteproc, and checks the RPMsg control endpoint. Expect `MCore started firmware=...` and a numbered heartbeat on the MCU serial terminal. + +Press Ctrl+C to stop following the journal. This does not stop the service. Check status independently: + +```bash +nxp-mcore status +ls -l /dev/nxp-temperature /dev/nxp-mcore-control +``` + +## Stopping the heartbeat application + +Lets now stop the heartbeat application: + +```bash +nxp-mcore stop +nxp-mcore status +journalctl -u nxp-mcore-test.service -b --no-pager -n 80 +``` + +Part 3 will require the application MCU be offline. + +## Additional details: Recovering ownership after an interrupted run + +An unexpected power cycle can leave the persistent manager work files while +the application MCU is offline. The updated manager archives verified ownership +from another Linux boot automatically. Legacy records without a boot ID, or +records from the current boot, require explicit recovery: + +```bash +python3 /usr/libexec/nxp-lp/firmware_manager.py recover --work /var/lib/nxp-mcore-test +``` + +Run this only after installing the updated manager from the source bundle. +See `MCU-RECOVERY.md` in the bundle for the no-reflash update commands. Recovery +holds the existing lock, requires an offline core and archives only recorded, +digest-matched files. Then load the desired ELF again. A manually loaded test +is not automatically restarted by a reboot. + +## What you have learned + +You can transfer and load the actual NXP FRDM i.MX 8M Plus MCU ELF, observe its foreground execution, and stop it through the control handshake. diff --git a/content/learning-paths/embedded-and-microcontrollers/nxp-imx8uplus-yocto-zephyr-part2/mcu-source.zip b/content/learning-paths/embedded-and-microcontrollers/nxp-imx8uplus-yocto-zephyr-part2/mcu-source.zip new file mode 100644 index 0000000000..66b468f605 Binary files /dev/null and b/content/learning-paths/embedded-and-microcontrollers/nxp-imx8uplus-yocto-zephyr-part2/mcu-source.zip differ diff --git a/content/learning-paths/embedded-and-microcontrollers/nxp-imx8uplus-yocto-zephyr-part2/prepare.md b/content/learning-paths/embedded-and-microcontrollers/nxp-imx8uplus-yocto-zephyr-part2/prepare.md new file mode 100644 index 0000000000..34080b6ab2 --- /dev/null +++ b/content/learning-paths/embedded-and-microcontrollers/nxp-imx8uplus-yocto-zephyr-part2/prepare.md @@ -0,0 +1,66 @@ +--- +title: "NXP FRDM i.MX 8M Plus: Prepare Linux and the MCU console" +description: "Verify the Part 1 integration and identify the correct MCU UART." +weight: 3 +layout: "learningpathall" +--- + +## Confirm the same board and image from part 1 + +On NXP FRDM i.MX 8M Plus through SSH: + +```bash +uname -m +cat /etc/nxp-lp/board.json +nxp-mcore status +systemctl status --with-dependencies greengrass-lite.target +``` + +You should see the NXP FRDM i.MX 8M Plus profile, `aarch64`, healthy Greengrass, and an **offline application Cortex-M7**. The helper selects by `fsl,imx8mn-cm7` in the running device tree. It refuses ambiguous matches. + +## Open the MCU DEBUG console + +When connecting the DEBUG USB port to your Ubuntu host, two specific USB ports will be discovered. The first USB UART is for the serial console. The second is for the M7 DEBUG console. Both ports should be set to **115200 baud, eight data bits, no parity, one stop bit, no flow control**. Use the board manual to identify the correct enumerated COM port; Linux's debug console and the MCU port are separate. + +On the Ubuntu host: + +```bash +ls /dev/ttyUSB* +picocom -b 115200 --flow n /dev/YOUR_MCU_DEBUG_PORT +``` + +## Additional Details: FRDM boot and memory reservations + +First inspect U-Boot's control tree with `fdt addr ${fdtcontroladdr}`, +`fdt print / model`, and `fdt print / compatible`. Require FRDM identity. The +reported failing board was using an EVK control DT despite FRDM Linux DTBs being +present on the card. Boot matching FRDM firmware from the correct SD/eMMC device +before loading M7. The bundle's `BOOT-SETUP.md` gives the detailed repair path. + + +Before loading any M7 ELF, use the corrected Part 1 image. Its reserved-memory +nodes must be named `vdev0vring0@55000000`, `vdev0vring1@55008000`, +`vdev0buffer@55400000`, and `rsc-table@550ff000`. Older bundles used `vring@...` +names which Linux does not match to its requested vring carveouts. Updating the +Zephyr ELF alone does not repair the deployed Linux DTB. + +The corrected Part 1 image automatically runs `prepare_mcore`, then +`bsp_bootcmd`, and selects its custom `imx8mp-frdm.dtb`. No additional manual +U-Boot settings are needed when that boot path is active. On Linux, view: + +```bash +cat /proc/device-tree/model +cat /proc/cmdline +``` + +You should see the FRDM identity and `clk-imx8mp.mcore_booted` in the command line on every +boot. An old saved U-Boot environment can override the corrected defaults; +`BOOT-SETUP.md` documents a temporary recovery boot and Part 1's setup page +explains the conditional one-time saved-environment repair. Use `bsp_bootcmd` +in that recovery path so a prior `bootflow` command cannot bypass `mmcargs`. +NXP's stock FRDM instructions instead select `imx8mp-frdm-rpmsg.dtb`; that tree +is a separate demo integration. This path modifies `imx8mp-frdm.dtb` directly. + +## What you have learned + +You can verify the matching image and offline application core, keep Linux and Greengrass available, and monitor the actual MCU serial console via the DEBUG serial port on the board. diff --git a/content/learning-paths/embedded-and-microcontrollers/nxp-imx8uplus-yocto-zephyr-part2/verify.md b/content/learning-paths/embedded-and-microcontrollers/nxp-imx8uplus-yocto-zephyr-part2/verify.md new file mode 100644 index 0000000000..2c8220758b --- /dev/null +++ b/content/learning-paths/embedded-and-microcontrollers/nxp-imx8uplus-yocto-zephyr-part2/verify.md @@ -0,0 +1,69 @@ +--- +title: "NXP FRDM i.MX 8M Plus: Verify MCU and Linux together" +description: "Observe heartbeat output, RPMsg delivery, and repeatable cleanup." +weight: 6 +layout: "learningpathall" +--- + +## Observe RPMmsg action in Yocto + +While the heartbeat runs in Zephyr on the MCU, the MCU DEBUG UART console in Yocto should show: + +```output +NXP FRDM i.MX 8M Plus: Zephyr on application MCU +MCU heartbeat 0 +MCU heartbeat 1 +MCU heartbeat 2 +``` + +On the board over SSH, optionally inspect the heartbeat through Linux's RPMsg TTY: + +```bash +python3 - <<'PYTHON' +import os, select, time, tty +fd = os.open("/dev/nxp-temperature", os.O_RDWR | os.O_NOCTTY | os.O_NONBLOCK) +try: + tty.setraw(fd) + os.write(fd, b"HELLO\n") + end = time.monotonic() + 10 + while time.monotonic() < end: + if select.select([fd], [], [], 0.5)[0]: + data = os.read(fd, 4096) + if not data: + break + os.write(1, data) +finally: + os.close(fd) +PYTHON +uname -m +uptime +systemctl status --with-dependencies greengrass-lite.target +``` + +You should see the MCU counter advancing its heartbeat count. + +Lastly, we can shut the heartbeat back down by running on the board: + +```bash +nxp-mcore stop +nxp-mcore status +``` + +Verify the offline state. This indicates the heartbeat has been shut down. + +## Additional details: Diagnosing faults + +| Symptom | Inspect | +| --- | --- | +| Entire board hangs at M7 start | Corrected FRDM clock override, `prepare_mcore` before Linux, named vring reservations, TCM ELF validation, and both serial logs; see bundle `HANG-FIX.md` | +| No remoteproc match | Correct machine image, loaded DTB, kernel remoteproc option, boot firmware, and `/etc/nxp-lp/board.json` | +| Attached/detached core | A bootloader demo or another owner is already running; correct startup ownership | +| Running core but no heartbeat | MCU console selection, correct local board target, UART ownership, and clocks | +| RPMsg aliases missing | RPMSG_TTY, endpoint source addresses, udev rules, vrings, fixed resource table, and the source patch | +| Stop acknowledgment missing | Separate control endpoint, application health, mailbox/cache configuration, and manager journal | + +Use `dmesg` and `journalctl -u nxp-mcore-test.service` for evidence. The heartbeat startup and RPMsg results above are user-reported hardware evidence. Stop/restart acceptance, physical BMP280 readings and AWS deployment remain to be tested; keep their logs separately. Finish with the test service stopped and the MCU offline, then continue with [Part 3](/learning-paths/embedded-and-microcontrollers/nxp-imx8uplus-gglite-zephyr-combined-part3/). + +## What you have learned + +You can verify that the Zephyr heartbeat is functioning and sending messages via RPMsg as well as and show repeatable MCU control and cleanup.