Use the AWS IoT Device SDK to communicate with the Greengrass nucleus, other components, and AWS IoT Core

To use the AWS IoT Device SDK for Java v2

1. Download the AWS IoT Device SDK for Java v2 (v1.2.10 or later).

2. Do one of the following to run your custom code in your component:

   • Build your component as a JAR file that includes the AWS IoT Device SDK, and run this JAR file in your component recipe.

   • Define the AWS IoT Device SDK JAR as a component artifact, and add that artifact to the classpath when you run your application in your component recipe.

3. Create a connection to the AWS IoT Greengrass Core IPC service. The IPC client, GreengrassCoreIPCClient, requires an EventStreamRPCConnection. Download the following IPCUtils class that provides this connection for you.

   /* Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
    * SPDX-License-Identifier: Apache-2.0 */
   
   package com.example.greengrass.util;
   
   import software.amazon.awssdk.crt.io.ClientBootstrap;
   import software.amazon.awssdk.crt.io.EventLoopGroup;
   import software.amazon.awssdk.crt.io.SocketOptions;
   import software.amazon.awssdk.eventstreamrpc.EventStreamRPCConnection;
   import software.amazon.awssdk.eventstreamrpc.EventStreamRPCConnectionConfig;
   import software.amazon.awssdk.eventstreamrpc.GreengrassConnectMessageSupplier;
   
   import java.util.concurrent.CompletableFuture;
   import java.util.concurrent.ExecutionException;
   
   public final class IPCUtils {
       // Port number is not used in domain sockets.
       // It is ignored but the field needs to be set when creating socket connection.
       public static final int DEFAULT_PORT_NUMBER = 8033;
       private static EventStreamRPCConnection clientConnection = null;
   
       private IPCUtils() {
   
       }
   
       public static EventStreamRPCConnection getEventStreamRpcConnection()
               throws ExecutionException, InterruptedException {
           String ipcServerSocketPath = System.getenv("AWS_GG_NUCLEUS_DOMAIN_SOCKET_FILEPATH_FOR_COMPONENT");
           String authToken = System.getenv("SVCUID");
           SocketOptions socketOptions = IPCUtils.getSocketOptionsForIPC();
   
           if (clientConnection == null) {
               clientConnection = connectToGGCOverEventStreamIPC(socketOptions, authToken, ipcServerSocketPath);
           }
           return clientConnection;
       }
   
       private static EventStreamRPCConnection connectToGGCOverEventStreamIPC(SocketOptions socketOptions,
                                                                              String authToken, String ipcServerSocketPath)
               throws ExecutionException, InterruptedException {
   
           try (EventLoopGroup elGroup = new EventLoopGroup(1);
                ClientBootstrap clientBootstrap = new ClientBootstrap(elGroup, null)) {
   
               final EventStreamRPCConnectionConfig config =
                       new EventStreamRPCConnectionConfig(clientBootstrap, elGroup, socketOptions, null,
                               ipcServerSocketPath, DEFAULT_PORT_NUMBER,
                               GreengrassConnectMessageSupplier.connectMessageSupplier(authToken));
               final CompletableFuture<Void> connected = new CompletableFuture<>();
               final EventStreamRPCConnection connection = new EventStreamRPCConnection(config);
               final boolean[] disconnected = {false};
               final int[] disconnectedCode = {-1};
               connection.connect(new EventStreamRPCConnection.LifecycleHandler() {
                   // Only called on successful connection.
                   @Override
                   public void onConnect() {
                       connected.complete(null);
                   }
   
                   @Override
                   public void onDisconnect(int errorCode) {
   
                       disconnected[0] = true;
                       disconnectedCode[0] = errorCode;
                       clientConnection = null;
                   }
   
                   // This on error is for any error that is connection level, including problems during connect()
                   @Override
                   public boolean onError(Throwable t) {
                       connected.completeExceptionally(t);
                       clientConnection = null;
                       return true; // True instructs handler to disconnect due to this error.
                   }
               });
               connected.get();
               return connection;
           }
       }
   
       private static SocketOptions getSocketOptionsForIPC() {
           SocketOptions socketOptions = new SocketOptions();
           socketOptions.connectTimeoutMs = 3000;
           socketOptions.domain = SocketOptions.SocketDomain.LOCAL;
           socketOptions.type = SocketOptions.SocketType.STREAM;
           return socketOptions;
       }
   }

4. Use the following code to create the IPC client.

   try (EventStreamRPCConnection eventStreamRPCConnection = IPCUtils.getEventStreamRpcConnection()) {
       GreengrassCoreIPCClient ipcClient = new GreengrassCoreIPCClient(eventStreamRPCConnection);
   } catch (Exception e) {
       LOGGER.log(Level.SEVERE, "Exception occurred when using IPC.", e);
       System.exit(1);
   }

To use the AWS IoT Device SDK for Python v2

1. Download the AWS IoT Device SDK for Python (v1.5.3 or later).

2. Add the SDK's installation steps to the install lifecycle in your component's recipe.

3. Create a connection to the AWS IoT Greengrass Core IPC service. Complete the following steps to create the IPC client and establish a connection.

   SDK v1.5.4 or later

   Use the following code to create the IPC client.

   import awsiot.greengrasscoreipc
   
   ipc_client = awsiot.greengrasscoreipc.connect()

   SDK v1.5.3

   1. Download the following IPCUtils class that provides the IPC server connection for you.

      # Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
      # SPDX-License-Identifier: Apache-2.0
      
      import os
      
      from awscrt.io import (
          ClientBootstrap,
          DefaultHostResolver,
          EventLoopGroup,
          SocketDomain,
          SocketOptions,
      )
      from awsiot.eventstreamrpc import Connection, LifecycleHandler, MessageAmendment
      
      TIMEOUT = 10
      
      
      class IPCUtils:
          def connect(self):
              elg = EventLoopGroup()
              resolver = DefaultHostResolver(elg)
              bootstrap = ClientBootstrap(elg, resolver)
              socket_options = SocketOptions()
              socket_options.domain = SocketDomain.Local
              amender = MessageAmendment.create_static_authtoken_amender(os.getenv("SVCUID"))
              hostname = os.getenv("AWS_GG_NUCLEUS_DOMAIN_SOCKET_FILEPATH_FOR_COMPONENT")
              connection = Connection(
                  host_name=hostname,
                  port=8033,
                  bootstrap=bootstrap,
                  socket_options=socket_options,
                  connect_message_amender=amender,
              )
              self.lifecycle_handler = LifecycleHandler()
              connect_future = connection.connect(self.lifecycle_handler)
              connect_future.result(TIMEOUT)
              return connection
      

   2. Use the following code to create the IPC client.

      import awsiot.greengrasscoreipc.client as client
      
      ipc_utils = IPCUtils()
      connection = ipc_utils.connect()
      ipc_client = client.GreengrassCoreIPCClient(connection)

To use the AWS IoT Device SDK for C++ v2

1. Download the AWS IoT Device SDK for C++ v2 (v1.13.0 or later).

2. Follow the installation instructions in the README to build the AWS IoT Device SDK for C++ v2 from source.

3. In your C++ build tool, link the Greengrass IPC library, AWS::GreengrassIpc-cpp, that you built in the previous step. The following CMakeLists.txt example links the Greengrass IPC library to a project that you build with CMake.

   cmake_minimum_required(VERSION 3.1)
   project (greengrassv2_pubsub_subscriber)
   
   file(GLOB MAIN_SRC
           "*.h"
           "*.cpp"
           )
   add_executable(${PROJECT_NAME} ${MAIN_SRC})
   
   set_target_properties(${PROJECT_NAME} PROPERTIES
           LINKER_LANGUAGE CXX
           CXX_STANDARD 11)
   find_package(aws-crt-cpp PATHS ~/sdk-cpp-workspace/build)
   find_package(EventstreamRpc-cpp PATHS ~/sdk-cpp-workspace/build)
   find_package(GreengrassIpc-cpp PATHS ~/sdk-cpp-workspace/build)
   target_link_libraries(${PROJECT_NAME} AWS::GreengrassIpc-cpp)

4. In your component code, create a connection to the AWS IoT Greengrass Core IPC service to create an IPC client (Aws::Greengrass::GreengrassCoreIpcClient). You must define an IPC connection lifecycle handler that handles IPC connection, disconnection, and error events. The following example creates an IPC client and an IPC connection lifecycle handler that prints when the IPC client connects, disconnects, and encounters errors.

   #include <iostream>
   
   #include <aws/crt/Api.h>
   #include <aws/greengrass/GreengrassCoreIpcClient.h>
   
   using namespace Aws::Crt;
   using namespace Aws::Greengrass;
   
   class IpcClientLifecycleHandler : public ConnectionLifecycleHandler {
       void OnConnectCallback() override {
           std::cout << "OnConnectCallback" << std::endl;
       }
   
       void OnDisconnectCallback(RpcError error) override {
           std::cout << "OnDisconnectCallback: " << error.StatusToString() << std::endl;
           exit(-1);
       }
   
       bool OnErrorCallback(RpcError error) override {
           std::cout << "OnErrorCallback: " << error.StatusToString() << std::endl;
           return true;
       }
   };
   
   int main() {
       // Create the IPC client.
       ApiHandle apiHandle(g_allocator);
       Io::EventLoopGroup eventLoopGroup(1);
       Io::DefaultHostResolver socketResolver(eventLoopGroup, 64, 30);
       Io::ClientBootstrap bootstrap(eventLoopGroup, socketResolver);
       IpcClientLifecycleHandler ipcLifecycleHandler;
       GreengrassCoreIpcClient ipcClient(bootstrap);
       auto connectionStatus = ipcClient.Connect(ipcLifecycleHandler).get();
       if (!connectionStatus) {
           std::cerr << "Failed to establish IPC connection: " << connectionStatus.StatusToString() << std::endl;
           exit(-1);
       }
       
       // Use the IPC client to create an operation request.
       
       // Activate the operation request.
       auto activate = operation.Activate(request, nullptr);
       activate.wait();
   
       // Wait for Greengrass Core to respond to the request.
       auto responseFuture = operation.GetResult();
       if (responseFuture.wait_for(std::chrono::seconds(timeout)) == std::future_status::timeout) {
           std::cerr << "Operation timed out while waiting for response from Greengrass Core." << std::endl;
           exit(-1);
       }
   
       // Check the result of the request.
       auto response = responseFuture.get();
       if (response) {
           std::cout << "Successfully published to topic: " << topic << std::endl;
       } else {
           // An error occurred.
           std::cout << "Failed to publish to topic: " << topic << std::endl;
           auto errorType = response.GetResultType();
           if (errorType == OPERATION_ERROR) {
               auto *error = response.GetOperationError();
               std::cout << "Operation error: " << error->GetMessage().value() << std::endl;
           } else {
               std::cout << "RPC error: " << response.GetRpcError() << std::endl;
           }
           exit(-1);
       }
       
       return 0;
   }
   

5. To run your custom code in your component, build your code as a binary artifact, and run the binary artifact in your component recipe. Set the artifact's Execute permission to OWNER to enable the AWS IoT Greengrass Core software to run the binary artifact.

   Your component recipe's Manifests section might look similar to the following example.

   JSON

   {
     ...
     "Manifests": [
       {
         "Lifecycle": {
           "Run": "{artifacts:path}/greengrassv2_pubsub_subscriber"
         },
         "Artifacts": [
           {
             "URI": "s3://DOC-EXAMPLE-BUCKET/artifacts/com.example.PubSubSubscriberCpp/1.0.0/greengrassv2_pubsub_subscriber",
             "Permission": {
               "Execute": "OWNER"
             }
           }
         ]
       }
     ]
   }

   YAML

   ...
   Manifests:
     - Lifecycle:
         Run: {artifacts:path}/greengrassv2_pubsub_subscriber
       Artifacts:
         - URI: s3://DOC-EXAMPLE-BUCKET/artifacts/com.example.PubSubSubscriberCpp/1.0.0/greengrassv2_pubsub_subscriber
           Permission:
             Execute: OWNER