Prerequisites

Progress checklist

• Tooling completed (incl. Python 3.12 + ESP-IDF)
• AWS profile and Region confirmed
• Mutation gate understood
• walkthrough.env copied and loaded
• NUC6CAY + ESP32-S3 on hand (OS prep is Prepare the core)

Before cloud steps, skim Concepts and Why Greengrass? if the hub vs direct-IoT choice is still fuzzy.

Tools and access

Finish Tooling first. Confirm access here before cloud steps.

Requirement	Detail
AWS CLIAWS CLI AWS Command Line Interface v2 — every cloud and deployment step in this walkthrough is a visible aws command, not a wrapper script. v2	latest — iot + greengrassv2
jq	1.6+ — cert JSON
Python	3.12 — Ubuntu 24.04 default on workstation (ESP-IDF) and NUC (components); see Tooling
ESP-IDF	≥ 5.1 (verified 5.3.2) — ESP32-S3
Profile	Named profile with IoT / IAM / Greengrass permissions (example: lab)
Region	ap-southeast-2
Mutation gate	export GG_EDGE_ALLOW_AWS=1 before agents mutate AWS (see below)
NUC6CAYNUC6CAY Intel NUC6CAY — compact x86 PC used as the Greengrass core in this lab (spare unit on hand; any quiet Ubuntu 24.04 x86 host works).	Hardware on hand — Ubuntu Server via the Ubuntu Server walkthrough ; lab names in Prepare the core
ESP32-S3ESP32-S3 Espressif ESP32-S3 — Wi‑Fi microcontroller used here as the Greengrass client device (not a second core).	USB flash; Wi‑Fi to the NUC’s LAN

Confirm profile

export AWS_PROFILE=lab
export AWS_REGION=ap-southeast-2
aws sts get-caller-identity
aws greengrassv2 help >/dev/null && echo greengrassv2_ok

{
    "UserId": "AROAEXAMPLE:you",
    "Account": "123456789012",
    "Arn": "arn:aws:sts::123456789012:assumed-role/AWSReservedSSO_AdministratorAccess_…/you"
}
greengrassv2_ok

Mutation gate

Agents authoring this repo refuse mutating AWS CLI unless GG_EDGE_ALLOW_AWS=1 is set. You run the walkthrough commands in your own shell; the gate is for agent sessions. Read-only describe / list / get / sts stay allowed without it.

Opt in for agent mutations

export GG_EDGE_ALLOW_AWS=1

(no output)

Unset gate

Without it, agent shell jobs stop with a refuse-to-mutate message and change nothing — deliberate, not an error.

Bill of materials

Part	Role
Intel NUC6CAY (spare unit on the shelf)	Greengrass corecore Greengrass core device — the Linux host running Nucleus (this lab: Intel NUC6CAY). Client devices discover and connect to it. host
ESP32-S3 DevKit (e.g. DevKitC-1)	Greengrass clientclient Greengrass client device — an IoT Thing (here the ESP32-S3) that discovers a core and uses local MQTT. It does not run Nucleus. zone (one required; up to three zones)
Momentary button (or onboard BOOT)	Sensor input — GPIO 0 on DevKitC-1
Onboard RGB (DevKitC-1)	Actuator — green = on (GPIO 48 default; 38 on DevKitC-1 v1.1)
USB cable	Flash / serial

Naming config

Copy env example

cp config/walkthrough.env.example config/walkthrough.env

(no output)

Edit config/walkthrough.env (gitignored). Then load it before every CLI page:

Load env and capture account ID

set -a && source config/walkthrough.env && set +a
export AWS_ACCOUNT_ID
AWS_ACCOUNT_ID=$(aws sts get-caller-identity --query Account --output text)
echo "$AWS_ACCOUNT_ID"

123456789012

Variable	Example purpose
AWS_REGION / AWS_PROFILE	CLI target
CORE_THING_NAME	NUC core ThingThing AWS IoT Thing — logical device identity bound to a certificate (core Thing on the NUC; client Thing on the ESP32-S3).
CORE_THING_GROUP	Thing groupThing group AWS IoT Thing group — deployment target for Greengrass cloud deployments (this lab: the core's group). for deployments
CLIENT_THING_NAME	Primary ESP32-S3 client Thing (…-esp32-1)
CLIENT_THING_PREFIX	Auth selectionRule prefix (…-esp32) — matches numbered clients
CLIENT_THING_NAME_2 / _3	Optional zone clients (…-esp32-2, …-esp32-3)
CORE_CERTS_DIR / CLIENT_CERTS_DIR	X.509X.509 X.509 certificates — device identity material created with create-keys-and-certificate and stored under certs/ (gitignored). output paths
CLIENT_CERTS_DIR_2 / _3	Optional — certs for extra zones (certs/client-2, client-3)
ARTIFACT_BUCKET	Not set in the file. Pages derive it as …-gg-artifacts-$AWS_ACCOUNT_ID (and …-gg-data-… for telemetry)
ZONE_TABLE / ALARM_TOPIC / COMMAND_FUNCTION	DynamoDB table, SNS topic, and Lambda names for the Wire into AWS pages
ALERT_EMAIL	Your address for the CloudWatch alarm email (confirm the SNS mail)
GG_ROOT	Nucleus root (/greengrass/v2)
NUC_USER / NUC_HOST	SSH target (fill on Prepare the core)

Note

No provision/deploy wrappers — each page shows raw aws with these names.

Cost warning

Things and certs are cheap, and a running Nucleus with MoquetteMoquette
aws.greengrass.clientdevices.mqtt.Moquette — local MQTT broker on the core. Not Mosquitto; client devices connect here over mTLS. mostly costs electricity. The AWS integration pages add usage-billed services: IoT Core messages and rule actions (two zones at 10 s send about 17,000 telemetry messages a day, each matched by three rules), S3 requests and storage, DynamoDB on-demand writes, a CloudWatch custom metric and alarm per zone, CloudWatch Logs ingestion, and a few minutes of a SageMaker ml.m5.large training job. Check current prices on the AWS Pricing Calculator for your Region. Teardown removes every resource when you finish.

Next

Concepts.