This tutorial explains how to use IoT Application Kit (IoT AppKit) in a React web application.

AWS IoT TwinMaker (TwinMaker) is an AWS IoT service that you can use to build operational digital twins of physical and digital systems.

IoT AppKit is an open-source library that offers a variety of React components and a TwinMaker data source specifically developed to enable your IoT and digital twin applications.

To work with AWS IoT TwinMaker in this tutorial, you will need:

1. An AWS Account and the necessary permissions to use AWS IoT TwinMaker. If you already have an AWS IoT TwinMaker set up, you can proceed to the next section. Otherwise, follow the instructions to set up an account and configure authentication. The instructions will guide you through the necessary steps to ensure successful completion.

2. An AWS IoT TwinMaker workspace. If you already have an AWS IoT TwinMaker workspace set up, you can proceed to the next section. Otherwise, follow the instructions to create one.

3. The Cookie Factory v2 demo deployed to your AWS account. Resources created for the demo will be used in this tutorial.

4. Minimum versions of Node.js, npm, and an IDE or simple code editor installed.

   • Node.js 16+. npm recommends using a Node version manager, e.g. nvm to install Node.js and npm.

   • npm 8+. npm is automatically installed when you install Node.js or a Node.js version manager.

   • An IDE or code editor of your choice, e.g. AWS Cloud9 or Visual Studio Code.

5. A React starter project. To ensure your project is properly configured for this tutorial, complete the Create a basic web application with React, Typescript, and webpack tutorial to create a basic React project with the required dependencies and configuration.

Learn how to use IoT AppKit to build IoT-enabled React web applications.

You will learn about implementing IoT AppKit and using it to build a web application that will visualize Cookie Factory Freezer Tunnel temperature data.

• Installing IoT AppKit packages
• Importing IoT AppKit modules
• Importing IoT AppKit styles
• Setting your AWS credentials
• Setting your AWS IoT TwinMaker workspace name
• Creating an AWS IoT TwinMaker history query
• Creating a time series query
• Understanding WebglContext
• Putting it all together

IoT AppKit is a collection of npm packages you install individually as needed based on your application requirements.

npm install -S @iot-app-kit/react-components @iot-app-kit/source-iottwinmaker

import { LineChart, WebglContext } from '@iot-app-kit/react-components';
import { initialize, type TwinMakerEntityHistoryQuery } from '@iot-app-kit/source-iottwinmaker';

So your charts look and behave as expected, you should import the IoT AppKit styles in one of your application components.

import '@iot-app-kit/components/styles.css';

The application will access resources in your AWS account. Update the __FILL_IN__ placeholder values specific to your AWS account credentials.

const AWS_CREDENTIALS_ACCESS_KEY_ID: string = '__FILL_IN__';
const AWS_CREDENTIALS_SECRET_ACCESS_KEY: string = '__FILL_IN__';
const AWS_CREDENTIALS_SESSION_TOKEN: string = '__FILL_IN__';
const AWS_CREDENTIALS_EXPIRATION_IN_MS: number = __FILL_IN__;
const AWS_REGION: string = '__FILL_IN__';

The application will use resources created for the Cookie Factory v2 demo. Update the __FILL_IN__ placeholder value with the name of the AWS IoT TwinMaker workspace you created when deploying the demo.

const AWS_IOT_TWINMAKER_WORKSPACE_NAME: string = '__FILL_IN__';

To query data from AWS IoT TwinMaker using IoT AppKit, you create AWS IoT TwinMaker entity history queries (TwinMakerEntityHistoryQuery) for the entities and properties of interest.

For the application, create the entity history query for the Freezer Tunnel property Temperature as defined on the CookieLineComponent component.

import type { TwinMakerEntityHistoryQuery } from '@iot-app-kit/source-iottwinmaker';

const historyQuery: TwinMakerEntityHistoryQuery = {
  componentName: 'CookieLineComponent',
  entityId: 'FREEZER_TUNNEL_e12e0733-f5df-4604-8f10-417f49e6d298',
  properties: [
    {
      propertyName: 'Temperature',
    },
  ],
};

You create a time series query by passing a AWS IoT TwinMaker entity history query to the query module's timeSeriesData method. A time series query (TimeSeriesDataQuery) is the type of query IoT AppKit components actually use to fetch data.

import { initialize } from '@iot-app-kit/source-iottwinmaker';

const { query } = initialize('__YOUR_TWINMAKER_WORKSPACE_NAME__', { ... });

const timeSeriesQuery = query.timeSeriesData(historyQuery);

WebglContext is a WebGL context provider. It creates the <canvas> target element that IoT AppKit visualization components use to render time series data.

NOTE: This component is required and should be imported and used one time as a child of your root-level component

import { WebglContext } from '@iot-app-kit/react-components';

export function App() {
  return (
    <>
      <main>{ ... }</main>
      <WebglContext />
    </>
  );
}

Let's build the application! Using your React starter project:

npm install -S @iot-app-kit/react-components @iot-app-kit/source-iottwinmaker

Create the file.

touch src/styles.css

Open src/styles.css, paste the following CSS code, and save the file.

/* Set the application container to the size of the browser viewport and center the content */
#app {
  display: flex;
  flex-direction: column;
  justify-content: center;
  align-items: center;
  width: 100vw;
  height: 100vh;
}

/* Set a size on the chart container so that the IoT AppKit component sizes itself accordingly */
.chart {
  width: 90%;
  height: 40%;
}

Open src/index.tsx, delete the existing code, paste the following React code, and save the file.

NOTE: You must update the __FILL_IN__ placeholder values with your AWS account credentials and AWS IoT TwinMaker workspace name.

import { createRoot } from 'react-dom/client';

// Import IoT AppKit modules and types
import { LineChart, WebglContext } from '@iot-app-kit/react-components';
import { initialize, type TwinMakerEntityHistoryQuery } from '@iot-app-kit/source-iottwinmaker';

// Import IoT AppKit styles
import '@iot-app-kit/components/styles.css';

// Import application styles
import './styles.css';

// Your AWS account credentials
const AWS_CREDENTIALS_ACCESS_KEY_ID: string = '__FILL_IN__';
const AWS_CREDENTIALS_SECRET_ACCESS_KEY: string = '__FILL_IN__';
const AWS_CREDENTIALS_SESSION_TOKEN: string = '__FILL_IN__';
const AWS_CREDENTIALS_EXPIRATION_IN_MS: number = __FILL_IN__;
const AWS_REGION: string = '__FILL_IN__';

// Your AWS IoT TwinMaker workspace name
const AWS_IOT_TWINMAKER_WORKSPACE_NAME: string = '__FILL_IN__';

// Initialize the AWS IoT TwinMaker data source
const { query } = initialize(AWS_IOT_TWINMAKER_WORKSPACE_NAME, {
  awsCredentials: {
    accessKeyId: AWS_CREDENTIALS_ACCESS_KEY_ID,
    expiration: new Date(AWS_CREDENTIALS_EXPIRATION_IN_MS),
    secretAccessKey: AWS_CREDENTIALS_SECRET_ACCESS_KEY,
    sessionToken: AWS_CREDENTIALS_SESSION_TOKEN,
  },
  awsRegion: AWS_REGION,
});

// Create the AWS IoT TwinMaker entity history query
const historyQuery: TwinMakerEntityHistoryQuery = {
  componentName: 'CookieLineComponent',
  entityId: 'FREEZER_TUNNEL_e12e0733-f5df-4604-8f10-417f49e6d298',
  properties: [
    {
      propertyName: 'Temperature',
    },
  ],
};

// Create the time series query
const timeSeriesDataQuery = query.timeSeriesData(historyQuery);

const element = document.getElementById('app');

if (element) {
  createRoot(element).render(<App />);
}

function App() {
  return (
    <>
      <h2>My Line Chart Application</h2>
      <section className="chart">
        {/* Pass the time series query to the LineChart component
            and set the time window to 15 minutes from live */}
        <LineChart queries={[timeSeriesDataQuery]} viewport={{ duration: '15m' }} />
      </section>
      <WebglContext />
    </>
  );
}

npm run dev

Navigate to https://localhost:8080. Your application will look similar to this view but with your property data.