Skip to content

Greengrass MQTT tutorial

In this tutorial you build a Python AWS IoT Greengrass v2 component with @aws/nx-plugin, run it on an Ubuntu 26.04 x86_64 EC2 instance that acts as the core device, and watch its heartbeat arrive in AWS IoT Core over MQTT. You then change the source, publish the next version with NEXT_PATCH, remove the component from the device, and delete every resource you created.

The tutorial uses CDK and the classic Greengrass nucleus. For TypeScript components, Terraform, or an existing fleet, read the Greengrass component guide.

PieceWhereCreated by
Python project greengrass_tutorial.telemetrypackages/telemetrypy#project
Component com.example.Pulsepackages/telemetry/greengrass/pulsegreengrass#component
Greengrass core constructs and the Pulse app constructpackages/common/constructs/src/core/greengrass, packages/common/constructs/src/app/greengrassgreengrass#component
CDK application @greengrass-tutorial/infrapackages/infrats#infra

The generated component publishes over local Greengrass IPC. Module 1 changes it to publish to AWS IoT Core, which needs a different IPC operation, a different recipe authorization, and an IoT policy statement on the device. The API and access-control names come from the AWS IoT Core MQTT IPC documentation.

ResourceCreated byDeleted by
IoT thing group, thing, certificate, IoT policy, token exchange role, role alias, IAM access policyThe setup script and the nucleus installerThe script’s cleanup operation
EC2 t3.small instance with an SSM instance profileThe setup script (instance) and you (instance profile)The script’s cleanup operation and you
Artifact bucket, component versions, deployment, artifact read grantYour CDK stackdestroy, then manual deletion of the retained bucket, versions and deployments

The instance runs until you clean up. Use an AWS account and Region you can clean up completely.

  • Git
  • Node >= 22.13 (We recommend using something like NVM to manage your node versions)
    • verify by running node --version
  • UV >= 0.5.29
    1. install Python 3.14 by running: uv python install 3.14
    2. verify with uv python list --only-installed

You also need:

  • AWS CLI v2 with a named profile for the target account.
  • Permissions in that account to create IAM roles and policies, IoT things and policies, EC2 instances, Systems Manager commands, S3 buckets, CloudFormation stacks and Greengrass resources.
  • A default VPC in the Region, or a subnet with outbound internet access that you pass to the setup script.

Every AWS CLI command in this tutorial passes --profile and --region explicitly, and every CDK command receives AWS_PROFILE and AWS_REGION. Set the values once in your shell:

Terminal window
export TUTORIAL_AWS_PROFILE=<your-profile>
export TUTORIAL_AWS_REGION=us-east-1
export TUTORIAL_PREFIX=gg-tutorial

TUTORIAL_PREFIX names every resource the setup script creates. Pick a value that nothing else in the account uses.

The commands, source edits, build and CDK synthesis of this tutorial are covered by the greengrass-tutorial smoke test in CI. The setup script’s identity, refusal and cleanup behaviour runs against a recorded AWS CLI in the docs test suite.

Provisioning, MQTT delivery, device updates and cleanup require an AWS account and remain outside the automated lane. Follow the device checks in each module to verify the deployment. The hardware support table records the supported device platforms.

  1. Create the component: workspace, Python project, component, CDK application, and the switch to AWS IoT Core MQTT.
  2. Provision the core device: instance profile, image selection, the setup script, and what it creates.
  3. Deploy, observe and update: the CDK stack, the first deployment, the MQTT heartbeat, and a NEXT_PATCH update.
  4. Remove and clean up: an empty deployment revision, stack destruction, and deletion of the retained and script-created resources.