### Verify Greengrass Core Setup

Source: https://github.com/aws-greengrass/aws-greengrass-nucleus/blob/main/src/main/java/com/aws/greengrass/easysetup/README.md

After installation, use these commands to verify the Greengrass Core setup. 'tree' shows the directory structure, 'service greengrass status' checks the service status, and 'journalctl -u greengrass -f' follows the Greengrass logs for real-time monitoring.

```bash
# Verify the setup
tree ~/gg_home/
sudo service greengrass status
sudo journalctl -u greengrass -f
```

--------------------------------

### Dependency Tree Example

Source: https://github.com/aws-greengrass/aws-greengrass-nucleus/blob/main/src/test/greengrass-nucleus-benchmark/src/main/java/com/aws/greengrass/jmh/packagemanager/Readme.md

Illustrates the dependency tree structure for Python packages awscli and boto3, used in the local component store for the benchmark.

```plaintext
awscli==1.16.144
  - botocore [required: ==1.12.134, installed: 1.12.134]
    - docutils [required: >=0.10, installed: 0.14]
    - jmespath [required: >=0.7.1,<1.0.0, installed: 0.9.4]
    - python-dateutil [required: >=2.1,<3.0.0, installed: 2.8.1]
      - six [required: >=1.5, installed: 1.14.0]
    - urllib3 [required: >=1.20,<1.25, installed: 1.24.2]
  - colorama [required: >=0.2.5,<=0.3.9, installed: 0.3.9]
  - docutils [required: >=0.10, installed: 0.14]
  - PyYAML [required: >=3.10,<=3.13, installed: 3.13]
  - rsa [required: >=3.1.2,<=3.5.0, installed: 3.4.2]
    - pyasn1 [required: >=0.1.3, installed: 0.4.5]
  - s3transfer [required: >=0.2.0,<0.3.0, installed: 0.2.0]
    - botocore [required: >=1.12.36,<2.0.0, installed: 1.12.134]
      - docutils [required: >=0.10, installed: 0.14]
      - jmespath [required: >=0.7.1,<1.0.0, installed: 0.9.4]
      - python-dateutil [required: >=2.1,<3.0.0, installed: 2.8.1]
        - six [required: >=1.5, installed: 1.14.0]
      - urllib3 [required: >=1.20,<1.25, installed: 1.24.2]

boto3==1.9.128
  - botocore [required: >=1.12.128,<1.13.0, installed: 1.12.134]
    - docutils [required: >=0.10, installed: 0.14]
    - jmespath [required: >=0.7.1,<1.0.0, installed: 0.9.4]
    - python-dateutil [required: >=2.1,<3.0.0, installed: 2.8.1]
      - six [required: >=1.5, installed: 1.14.0]
    - urllib3 [required: >=1.20,<1.25, installed: 1.24.2]
  - jmespath [required: >=0.7.1,<1.0.0, installed: 0.9.4]
  - s3transfer [required: >=0.2.0,<0.3.0, installed: 0.2.0]
    - botocore [required: >=1.12.36,<2.0.0, installed: 1.12.134]
      - docutils [required: >=0.10, installed: 0.14]
      - jmespath [required: >=0.7.1,<1.0.0, installed: 0.9.4]
      - python-dateutil [required: >=2.1,<3.0.0, installed: 2.8.1]
        - six [required: >=1.5, installed: 1.14.0]
      - urllib3 [required: >=1.20,<1.25, installed: 1.24.2]
```

--------------------------------

### Get Help for UAT Parameters

Source: https://github.com/aws-greengrass/aws-greengrass-nucleus/blob/main/DEVELOPING.md

Display help information for parameters that can be supplied when running UATs locally. This command lists available options and their descriptions.

```bash
java -jar uat/target/nucleus-uat-artifact.jar -help
```

--------------------------------

### Install Greengrass Core with Zip File

Source: https://github.com/aws-greengrass/aws-greengrass-nucleus/blob/main/src/main/java/com/aws/greengrass/easysetup/README.md

Use these commands to move the Greengrass zip file, set up AWS credentials, unzip the archive, and launch the Greengrass Core. Ensure you replace placeholders like <test-device>, <test-group>, and <posixUser>:<posixGroup> with your specific values. The Java command requires the root directory for Greengrass home and specifies various configuration parameters.

```bash
# Move aws.greengrass.nucleus.zip to test device
# Set up aws creds
unzip aws.greengrass.nucleus.zip -d GreengrassCore
sudo java -Droot=~/gg_home -jar ./GreengrassCore/lib/Greengrass.jar -p true -ar us-east-1 -tn <test-device> -tgn <test-group> -ss true -u <posixUser>:<posixGroup>
```

--------------------------------

### Merge Configuration: Type Change Example

Source: https://github.com/aws-greengrass/aws-greengrass-nucleus/blob/main/CONFIGURE_COMPONENT_README.md

Demonstrates merging a new value that changes the type of an existing key from a string to an object.

```json
{
    "MERGE": {
        "myKey": {
            "nestedKey1": "myValue"
        }
    }
}
```

--------------------------------

### Class with Injected Dependency

Source: https://github.com/aws-greengrass/aws-greengrass-nucleus/blob/main/src/main/java/com/aws/greengrass/dependency/README.md

Example of a class that has a dependency on another class (Engine) which will be injected automatically.

```java
class Bogon {
    @Inject Engine engine;
}
```

--------------------------------

### Static System Configuration

Source: https://github.com/aws-greengrass/aws-greengrass-nucleus/blob/main/README_CONFIG_SCHEMA.md

Defines system configurations that are set during kernel setup and are not changed by deployments. This includes paths for certificates, keys, and the root CA.

```yaml
system: 
  rootPath: "/greengrass/v2"
  thingName: "test_thing"
  certificateFilePath: "root/thingCert.crt"
  privateKeyPath: "root/privKey.key"
  rootCaPath: "root/rootCA.pem"
```

--------------------------------

### Get an Object from Context

Source: https://github.com/aws-greengrass/aws-greengrass-nucleus/blob/main/src/main/java/com/aws/greengrass/dependency/README.md

Retrieve an object of a specific class from the Context. If the object does not exist, it will be created using its default constructor and its lifecycle will begin if applicable.

```java
Bogon bogon = c.get(Bogon.class);
```

--------------------------------

### IoT Policy for Endpoint Switch

Source: https://github.com/aws-greengrass/aws-greengrass-nucleus/blob/main/README_CONFIG_SCHEMA.md

An example IoT policy resource ARN pattern required to allow MQTT connections during endpoint-switch deployments. This pattern ensures the client ID format `<thingName>#endpoint-switch` is permitted.

```json
"Resource": "arn:aws:iot:*:*:client/${iot:Connection.Thing.ThingName}*"
```

--------------------------------

### Example Aggregated Metric Log Entry

Source: https://github.com/aws-greengrass/aws-greengrass-nucleus/blob/main/src/main/java/com/aws/greengrass/telemetry/README.md

This JSON structure represents a single log entry for aggregated metrics. It includes timestamps, namespaces, and a list of metrics with their aggregated values and units.

```json
{
    "thread": "pool-3-thread-3",
    "level": "TRACE",
    "eventType": null,
    "message": "{\"TS\":1599790572560,\"NS\":\"GreengrassComponents\",\"M\":[{\"N\":\"NumberOfComponentsStopping\",\"Average\":0.0,\"U\":\"Count\"},{\"N\":\"NumberOfComponentsFinished\",\"Average\":1.0,\"U\":\"Count\"},{\"N\":\"NumberOfComponentsRunning\",\"Average\":11.0,\"U\":\"Count\"},{\"N\":\"NumberOfComponentsNew\",\"Average\":0.0,\"U\":\"Count\"},{\"N\":\"NumberOfComponentsBroken\",\"Average":0.0,\"U\":\"Count\"},{\"N\":\"NumberOfComponentsErrored\",\"Average":0.0,\"U\":\"Count\"},{\"N\":\"NumberOfComponentsStarting\",\"Average":0.0,\"U\":\"Count\"},{\"N\":\"NumberOfComponentsInstalled\",\"Average":0.0,\"U\":\"Count\"},{\"N\":\"NumberOfComponentsStateless\",\"Average":0.0,\"U\":\"Count\"}]}",
    "contexts": {},
    "loggerName": "Metrics-AggregateMetrics",
    "timestamp": 1599790572565,
    "cause": null
}
```

--------------------------------

### Prepare and Run E2E Tests

Source: https://github.com/aws-greengrass/aws-greengrass-nucleus/blob/main/DEVELOPING.md

Re-build all tests with test resources and execute only the E2E tests. This requires AWS credentials and network access.

```bash
mvn -ntp generate-test-sources test-compile -DskipTests
mvn surefire:test@integration-tests -Dgroups="E2E" -DexcludedGroups="" -Dsurefire.argLine=""
```

--------------------------------

### Create a Context Object

Source: https://github.com/aws-greengrass/aws-greengrass-nucleus/blob/main/src/main/java/com/aws/greengrass/dependency/README.md

Instantiate a new Context object to begin managing dependencies.

```java
Context context = new Context();
```

--------------------------------

### Build Greengrass Nucleus Jar with Maven

Source: https://github.com/aws-greengrass/aws-greengrass-nucleus/blob/main/src/main/java/com/aws/greengrass/easysetup/README.md

Use this command to build the Greengrass Nucleus fat jar. Check build logs for the jar's location.

```bash
mvn clean package
```

--------------------------------

### Initialize MetricFactory

Source: https://github.com/aws-greengrass/aws-greengrass-nucleus/blob/main/src/main/java/com/aws/greengrass/telemetry/README.md

Initializes a MetricFactory to specify the log file for emitting metrics. If not specified, metrics are written to 'generic.log'.

```java
MetricFactory metricFactory = new MetricFactory("GreengrassComponents");
```

--------------------------------

### Run All Tests

Source: https://github.com/aws-greengrass/aws-greengrass-nucleus/blob/main/DEVELOPING.md

Execute all tests, including unit and integration tests. This command provides a comprehensive test run.

```bash
mvn verify
```

--------------------------------

### Service Dependency Configuration

Source: https://github.com/aws-greengrass/aws-greengrass-nucleus/blob/main/README_CONFIG_SCHEMA.md

Illustrates how to define dependencies between services, specifying the dependency type as SOFT or HARD.

```yaml
myCustomService:
  dependencies:
    - <serviceName>:<dependencyType>
```

--------------------------------

### Service Lifecycle Configuration

Source: https://github.com/aws-greengrass/aws-greengrass-nucleus/blob/main/README_CONFIG_SCHEMA.md

Details the configuration options for various service lifecycle steps, including script execution, environment variables, and timeouts.

```yaml
<serviceName>:
  lifecycle:
    setenv: # This applies to all lifecycle steps
      <key>: <defaultValue>

    bootstrap:
      requiresPrivilege: true|false # Optional. Run with root privileges.
      script:
      setenv: # Optional. Key-value environment variables. It can override the parent 'setenv'.
      timeout: # Optional. Timeout in number of seconds. Default to 120 sec.

    install:
      requiresPrivilege: # Optional. Run with root privileges.
      script:
      setenv: # Optional. Key-value environment variables. It can override the parent 'setenv'.
      skipif: onpath <executable>|exists <file> # Optional.
      timeout: # Optional. Timeout in number of seconds. Default to 120 sec.
      
    startup: # This step is mutually exclusive from 'run'.
      requiresPrivilege: # Optional. Run with root privileges.
      script:
      setenv:
      skipif: onpath <executable>|exists <file> # Optional.
      timeout: # Optional. Timeout in number of seconds. Default to 120 sec.

    run: # This step is mutually exclusive from 'startup'.
      requiresPrivilege: # Optional. Run with root privileges.
      script:
      setenv:
      skipif: onpath <executable>|exists <file> # Optional.
      timeout: # Optional. Timeout in number of seconds. Default to no timeout.
      
    shutdown: # This step can co-exist with both startup and run
      requiresPrivilege: # Optional. Run with root privileges.
      script:
      setenv:
      skipif: onpath <executable>|exists <file> # Optional.
      timeout: # Optional. Timeout in number of seconds. Default to 15 seconds.
    
    recover: # This step runs every time service enters error state.
      requiresPrivilege: # Optional. Run with root privileges.
      script:
      setenv:
      skipif: onpath <executable>|exists <file> # Optional.
      timeout: # Optional. timeout in number of seconds. Default to 60 sec.
```

--------------------------------

### Run JMH Benchmark Jar

Source: https://github.com/aws-greengrass/aws-greengrass-nucleus/blob/main/src/test/greengrass-nucleus-benchmark/readme.md

Execute the shaded JMH benchmark jar with memory profiler and native memory tracking enabled. Use -h for JMH command line options.

```bash
java -jar target/benchmarks.jar -wi 0 -f 1 -i 1 -prof com.aws.greengrass.jmh.profilers.ForcedGcMemoryProfiler -jvmArgs "-XX:NativeMemoryTracking=summary"
```

```bash
java -jar target/benchmarks.jar -h
```

--------------------------------

### Create a Telemetry Metric

Source: https://github.com/aws-greengrass/aws-greengrass-nucleus/blob/main/src/main/java/com/aws/greengrass/telemetry/README.md

Defines a new metric with its namespace, name, aggregation type, and unit. This should be done once per metric.

```java
Metric metric = Metric.builder()
        .namespace("GreengrassComponents")
        .name("NumberOfComponentsInstalled")
        .unit(TelemetryUnit.Count)
        .aggregation(TelemetryAggregation.Average)
        .build();
```

--------------------------------

### Run E2E Tests in Parallel

Source: https://github.com/aws-greengrass/aws-greengrass-nucleus/blob/main/DEVELOPING.md

Append these flags to the E2E test command to enable parallel execution of test classes, up to the number of available CPU cores. Note that tests within the same class should not run in parallel due to shared global resources.

```bash
-DforkCount=1C -DreuseForks=false
```

--------------------------------

### Run Unit Tests

Source: https://github.com/aws-greengrass/aws-greengrass-nucleus/blob/main/DEVELOPING.md

Execute only the unit tests for the Greengrass project. This command is useful for quick checks during development.

```bash
mvn test
```

--------------------------------

### Build Greengrass Nucleus

Source: https://github.com/aws-greengrass/aws-greengrass-nucleus/blob/main/DEVELOPING.md

Build the Greengrass Nucleus artifacts while skipping tests. The -U flag ensures that you are using the latest snapshots and releases of dependencies.

```bash
mvn -U -ntp install -DskipTests
```

--------------------------------

### MQTTClient Interface

Source: https://github.com/aws-greengrass/aws-greengrass-nucleus/wiki/MQTT

The `MQTTClient` interface provides the primary means for interacting with MQTT operations within Greengrass Nucleus. It supports publishing, subscribing, and unsubscribing from MQTT topics. Implementations exist for both MQTT 3 and MQTT 5 protocols, with a preference for versions returning futures for asynchronous operations.

```APIDOC
## MQTTClient Interface

### Description
The `MQTTClient` interface is the central point for all MQTT-related operations in Greengrass Nucleus. It exposes methods for publishing messages, subscribing to topics, and unsubscribing from topics. Different implementations cater to MQTT 3 and MQTT 5 protocols, and versions returning futures are recommended for better asynchronous handling.

### Methods
- `publish(topic, payload, qos)`
- `subscribe(topic, qos)`
- `unsubscribe(topic)`

### Client ID Management
All MQTT connections require a unique client ID. When a new MQTT client is created, Nucleus automatically assigns the lowest available client ID number, appending it to the base client ID (e.g., `<thingName>#2`).

### Related Functions
- `getNewMqttClient()`: Creates and returns an appropriate MQTT client instance based on the configured MQTT version (defaulting to MQTT 5 as of version 2.10.0).
```

--------------------------------

### Custom IPC Socket Path Configuration

Source: https://github.com/aws-greengrass/aws-greengrass-nucleus/blob/main/README_CONFIG_SCHEMA.md

Configures a custom path for the IPC socket, relocating it from the default $GG_ROOT/ipc.socket. This setting does not apply to Windows systems.

```yaml
system: 
  ipcSocketPath: "/ipcFolder/ipc.socket"
```

--------------------------------

### Greengrass Watcher Interface

Source: https://github.com/aws-greengrass/aws-greengrass-nucleus/wiki/Configuration

Illustrates the Watcher interface and its extensions (Validator, Subscriber, ChildChanged) used for reacting to configuration changes. Avoid subscribing to specific topics that might be removed; instead, subscribe to a persistent parent and check for specific changes.

```java
Watcher.java
```

```java
Validator.java
```

```java
Subscriber.java
```

```java
ChildChanged.java
```

```java
GenericExternalService.java
L112-L113
```

```java
Node.java
L173
```

--------------------------------

### Greengrass Configuration Update Behavior

Source: https://github.com/aws-greengrass/aws-greengrass-nucleus/wiki/Configuration

Demonstrates how configuration merges based on timestamps. Older timestamps are ignored, and nested data is merged without removing keys by default. Use mergeMap with UpdateBehaviorTree for explicit key removal or replacement.

```java
Topics.java
L309
```

```java
UpdateBehaviorTree.java
```

```java
DeploymentActivator.java
L102-L145
```

--------------------------------

### Define Default Component Configuration (JSON)

Source: https://github.com/aws-greengrass/aws-greengrass-nucleus/blob/main/CONFIGURE_COMPONENT_README.md

Specifies the default configuration for a Greengrass V2 component using JSON format within the recipe file.

```json
{
   "ComponentConfiguration": {
      "DefaultConfiguration": {
         "singleLevelKey": "default value of singleLevelKey",
         "nestedObjectkey": {
            "leafKey": "default value of /nestedObjectkey/leafKey"
         },
         "listKey": [
            "item1",
            "item2"
         ],
         "emptyStringKey": "",
         "emptyListKey": [],
         "emptyMapKey": {},
         "defaultIsNullKey": null
      }
   }
}
```

--------------------------------

### Run UATs Locally

Source: https://github.com/aws-greengrass/aws-greengrass-nucleus/blob/main/DEVELOPING.md

Execute User Acceptance Tests locally using the generated UAT artifact. Ensure AWS credentials are set in your environment and specify the Greengrass Nucleus archive path.

```bash
java -Dggc.archive=target/aws.greengrass.nucleus.zip -Dtags="stable" -jar uat/target/nucleus-uat-artifact.jar
```

--------------------------------

### Emit Metric Data with Timestamp

Source: https://github.com/aws-greengrass/aws-greengrass-nucleus/blob/main/src/main/java/com/aws/greengrass/telemetry/README.md

Emits a metric data point by assigning a value and timestamp to the metric before putting it into the factory.

```java
metric.setValue(10);
metric.setTimestamp(Instant.now().toEpochMilli());

metricFactory.putMetricData(metric);
```

--------------------------------

### Run Integration Tests

Source: https://github.com/aws-greengrass/aws-greengrass-nucleus/blob/main/DEVELOPING.md

Execute only the integration tests for the Greengrass project. The -Dsurefire.argLine="" is used to clear any default arguments that might interfere with test execution.

```bash
mvn surefire:test@integration-tests -Dsurefire.argLine=""
```

--------------------------------

### Define Default Component Configuration (YAML)

Source: https://github.com/aws-greengrass/aws-greengrass-nucleus/blob/main/CONFIGURE_COMPONENT_README.md

Specifies the default configuration for a Greengrass V2 component using YAML format within the recipe file.

```yaml
ComponentConfiguration:
  DefaultConfiguration:
    singleLevelKey: default value of singleLevelKey
    nestedObjectkey:
      leafKey: default value of /nestedObjectkey/leafKey
    listKey:
      - 'item1'
      - 'item2'
    emptyStringKey: ''
    emptyListKey: []
    emptyMapKey: {}
    defaultIsNullKey: null
```

--------------------------------

### Constructor Injection with Named Dependencies

Source: https://github.com/aws-greengrass/aws-greengrass-nucleus/blob/main/src/main/java/com/aws/greengrass/dependency/README.md

Use constructor injection to provide named dependencies to a class. Only one constructor can be annotated with @Inject.

```java
class BogonWithNamedConstructorInjection {
    Engine leftEngine;
    Engine rightEngine;

    @Inject
    public BogonWithNamedConstructorInjection(@Named("left") Engine leftEngine, @Named("right") Engine rightEngine) {
        this.leftEngine = leftEngine;
        this.rightEngine = rightEngine;
        // more initialization logic with engines...
    }
}
```

--------------------------------

### Revert Greengrass Systemd Service File

Source: https://github.com/aws-greengrass/aws-greengrass-nucleus/blob/main/README_SYSTEMD_GUIDANCE.md

Run this command to modify the Greengrass systemd service file, reverting it to the configuration used in versions prior to 2.14.0. This addresses a service reliability issue.

```bash
sudo sed -i 's|ExecStart=/bin/sh -c "(.*) >> .*/logs/loader.log 2>&1"|ExecStart=/bin/sh \1|' /etc/systemd/system/greengrass.service
```