Skip to content

Commit

Permalink
chore: get started page updates
Browse files Browse the repository at this point in the history 
fix: 1
  • Loading branch information
Fernando Pauer committed Nov 26, 2024
1 parent 18385e6 commit 0f64335
Show file tree
Hide file tree
Showing 2 changed files with 224 additions and 143 deletions.
211 changes: 68 additions & 143 deletions apps/doc-site/stories/overview/GettingStarted.mdx
View file
Original file line number Diff line number Diff line change
@@ -1,173 +1,98 @@
import { Meta } from '@storybook/blocks';
import { Meta, Source } from '@storybook/blocks';

<Meta title="Overview/Getting started" />

# Tutorial : Getting started with IoT Application Kit
# Getting started

Use this step-by-step tutorial to learn how to set up IoT Application Kit.
Use this step-by-step guide to learn how to set up IoT Application Kit and [AWS IoT Sitewise](https://aws.amazon.com/iot-sitewise/) as a data source.

### Step 1: Install the required dependencies

To install with `npm`, run the following command.
The follow installing steps uses `npm`, however feel free to another package manager such as [yarn](https://classic.yarnpkg.com/en/docs/getting-started).

##### IoT App Kit and AWS SDK packages
1. `npm install --save @iot-app-kit/source-iotsitewise`
1. `npm install --save @iot-app-kit/source-iottwinmaker`
1. `npm install --save @iot-app-kit/react-components`
1. `npm install --save @iot-app-kit/scene-composer`
1. `npm install --save @aws-sdk/client-iotsitewise@^3.696.0`
1. `npm install --save @aws-sdk/client-iot-events@^3.354.0`

### Step 2: Initialize the AWS IoT SiteWise source
Do one of the following:
##### IoT App Kit is built with [React](https://react.dev/), please install these dependencies as well.
1. `npm install --save react@^18.3.1 react-dom@^18.3.1 [email protected] typescript@^4.9.5`

- Use the following code to initialize an instance of [@aws-sdk/client-iotsitewise]
(https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/clients/client-iotsitewise/index.html).
##### IoT App Kit has a direct dependency on [AWS Design System](https://cloudscape.aws.dev/)
1. `npm install --save @cloudscape-design/chat-components@^1.0.10`
1. `npm install --save @cloudscape-design/collection-hooks@^1.0.49`
1. `npm install --save @cloudscape-design/[email protected]`
1. `npm install --save @cloudscape-design/[email protected]`
1. `npm install --save @cloudscape-design/[email protected]`
1. `npm install --save @cloudscape-design/component-toolkit@^1.0.0-beta.62`

### Step 2: Initialize the AWS IoT SiteWise source
There are two options to initialize an sitewise data source:

```ts
import { initialize } from '@iot-app-kit/source-iotsitewise';
1. Use the following code to initialize an instance of [@aws-sdk/client-iotsitewise](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/clients/client-iotsitewise/index.html).

const { IoTSiteWiseClient } = require("@aws-sdk/client-iotsitewise");
<Source dark="true" code={`
import { IoTSiteWiseClient } from '@aws-sdk/client-iotsitewise';
import { initialize } from '@iot-app-kit/source-iotsitewise';
const iotSiteWiseClient = new IoTSiteWiseClient({ region: "REGION" });
const iotSiteWiseClient = new IoTSiteWiseClient({ region: "REGION" });
const { query } = initialize({ iotSiteWiseClient });
```
const { query } = initialize({ iotSiteWiseClient });
`} />

- Use the following code to initialize an instance of [@aws-sdk/credential-providers](https://www.npmjs.com/package/@aws-sdk/credential-providers).
2. Use the following code to initialize an instance of [@aws-sdk/credential-providers](https://www.npmjs.com/package/@aws-sdk/credential-providers).
Replace the credential provider with a provider of your choice.

```ts
import { initialize } from '@iot-app-kit/source-iotsitewise';
import { fromCognitoIdentity } from "@aws-sdk/credential-providers";
<Source dark="true" code={`
import { initialize } from '@iot-app-kit/source-iotsitewise';
import { fromCognitoIdentity } from "@aws-sdk/credential-providers";
const { query } = initialize({ awsCredentials: fromCognitoIdentity(...) });
```in your a
const { query } = initialize({ awsCredentials: fromCognitoIdentity(...) });
`} />

### Step 3: Include the style sheets

The following code shows how to include the stylesheets.

```ts
<Source dark="true" code={`
import "@iot-app-kit/components/styles.css";
```
`} />

### Step 4: Mount the components

The follwing example code explains how to mount the components.

```tsx
import { initialize } from '@iot-app-kit/source-iotsitewise';
import { Chart, WebglContext } from '@iot-app-kit/react-components';
const { IoTSiteWiseClient } = require("@aws-sdk/client-iotsitewise");

const iotSiteWiseClient = new IoTSiteWiseClient({ region: "REGION" });
const { query } = initialize({ iotSiteWiseClient });

// React component example
<Chart
queries={[
query.timeSeriesData(
{
assets: [{
// Replace sitewse-asset-id with the ID of your AWS IoT SiteWise asset.
assetId: 'sitewise-asset-id',
// Replace property-id with the ID of your AWS IoT SiteWise asset property.
properties: [{ propertyId: 'property-id' }],
}]
}
)
]}
/>
<WebglContext />
```

The IoT App Kit components is supported across all modern browsers, including IE11.
IoT App Kit components utilizes WebGLusers which is documented in the componenets documentation.
Users with misconfigured or missing graphics drivers may face problems.

### Step 5: Initialize the AWS IoT TwinMaker source

Here is a list of [@aws-sdk/credential-providers](https://www.npmjs.com/package/@aws-sdk/credential-providers).
Replace the credential provider with a provider of your choice.

```tsx
import { initialize } from '@iot-app-kit/source-iottwinmaker';
import { fromCognitoIdentity } from "@aws-sdk/credential-providers";

// Replace twin-maker-workspace-id with the ID of your AWS IoT TwinMaker workspace, and replace
// REGION with the region of your workspace.
const { query } = initialize('twin-maker-workspace-id', { awsCredentials: fromCognitoIdentity(...), awsRegion: 'REGION' });
```

### Step 6: Mount the SceneViewer component

The following example explains how to mount the SceneViewer component.

```tsx
import { initialize, TwinMakerQuery } from '@iot-app-kit/source-iottwinmaker';
import { SceneViewer } from '@iot-app-kit/scene-composer';

const { query, s3SceneLoader } = initialize( ... );
// Replace scene-id with the ID of your AWS IoT TwinMaker scene in the workspace.
const sceneLoader = s3SceneLoader('scene-id');
const queries: TwinMakerQuery[] = [
{
// Replace entity-id with the ID of your AWS IoT TwinMaker entity in the workspace.
entityId: 'entity-id',
// Replace component-name with the name of the component for your entity.
componentName: 'component-name',
// Replace property-name with the name of the property for your component.
properties: [{ propertyName: 'property-name' }],
},
{
// Replace component-type-id with the ID of your concrete AWS IoT TwinMaker component type in the workspace.
componentTypeId: 'component-type-id',
// Replace property-name with the name of the property for your component type.
properties: [{ propertyName: 'property-name' }],
},
];
const viewport = {
// Replace start-time with the start time to query data from your workspace.
start: new Date('start-time'),
// Replace end-time with the end time to query data from your workspace.
end: new Date('end-time'),
};

// React component example
<SceneViewer
sceneLoader={sceneLoader}
queries={queries}
viewport={viewport}
/>
```

### Step 7: Mount the VideoPlayer component

The following example explains how to mount the VideoPlayer component.

```tsx
import { initialize } from '@iot-app-kit/source-iottwinmaker';
import { VideoPlayer } from '@iot-app-kit/react-components';

const videoData = initialize( ... ).videoData({
// Replace entity-id with your AWS IoT TwinMaker entity that has KinesisVideoStream component
entityId: 'entity-id',
// Replace component-name with the name of the component for your entity that has KinesisVideoStreamName property
componentName: 'component-name',
});
// or
const videoData = initialize( ... ).videoData({
// Replace kvs-stream-name with your KinesisVideo stream name
kvsStreamName: 'kvs-stream-name',
});

// Video player for On-Demand playback mode with specified start and end time
<VideoPlayer
videoData={videoData}
// Replace start-time and end-time with the correct time to play the video.
viewport={{ start: new Date('start-time'), end: new Date('end-time') }}
/>

// Video player for Live playback mode
<VideoPlayer
videoData={videoData}
viewport={{ duration: '0' }}
/>
```
<Source dark="true" language="jsx" code={`
import { IoTSiteWiseClient } from '@aws-sdk/client-iotsitewise';
import { initialize } from '@iot-app-kit/source-iotsitewise';
import { Chart } from '@iot-app-kit/react-components';
import "@iot-app-kit/components/styles.css";
const iotSiteWiseClient = new IoTSiteWiseClient({ region: "REGION" });
const { query } = initialize({ iotSiteWiseClient });
// React component example
const MyApp = () => {
return (
<Chart
queries={[
query.timeSeriesData(
{
assets: [{
// Replace sitewse-asset-id with the ID of your AWS IoT SiteWise asset.
assetId: 'sitewise-asset-id',
// Replace property-id with the ID of your AWS IoT SiteWise asset property.
properties: [{ propertyId: 'property-id' }],
}]
}
)
]}
/>
);
}
`} />

For more information about [Asset IDs](https://docs.aws.amazon.com/iot-sitewise/latest/userguide/create-assets.html) and [Property IDs](https://docs.aws.amazon.com/iot-sitewise/latest/userguide/asset-properties.html), please visit our guides about [how to get started with AWS IoT Sitewise](https://docs.aws.amazon.com/iot-sitewise/latest/userguide/getting-started.html), or our guide [Use the AWS IoT SiteWise demo](https://docs.aws.amazon.com/iot-sitewise/latest/userguide/getting-started-demo.html)

For more information about Data source queries, please visit [AWS IoT SiteWise source documentation page](/iot-app-kit/?path=/docs/data-sources-aws-iot-sitewise--docs)
156 changes: 156 additions & 0 deletions apps/doc-site/stories/overview/GettingStartedWithTW.mdx
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,156 @@
import { Meta, Source } from '@storybook/blocks';

<Meta title="Overview/Getting started with IoT Twinmaker" />

# Getting started with IoT TwinMaker

Use this step-by-step guide to learn how to set up IoT Application Kit and [AWS IoT Twinmaker](https://aws.amazon.com/iot-twinmaker/) as a data source.

### Step 1: Install the required dependencies

The follow installing steps uses `npm`, however feel free to another package manager such as [yarn](https://classic.yarnpkg.com/en/docs/getting-started).

##### IoT App Kit and AWS SDK packages
1. `npm install --save @iot-app-kit/source-iottwinmaker`
1. `npm install --save @iot-app-kit/react-components`
1. `npm install --save @iot-app-kit/scene-composer`
1. `npm install --save @aws-sdk/client-iottwinmaker@^3.589.0`

##### IoT App Kit is built with [React](https://react.dev/), please install these dependencies as well.
1. `npm install --save react@^18.3.1 react-dom@^18.3.1 [email protected] typescript@^4.9.5`

##### IoT App Kit has a direct dependency on [AWS Design System](https://cloudscape.aws.dev/)
1. `npm install --save @cloudscape-design/chat-components@^1.0.10`
1. `npm install --save @cloudscape-design/collection-hooks@^1.0.49`
1. `npm install --save @cloudscape-design/[email protected]`
1. `npm install --save @cloudscape-design/[email protected]`
1. `npm install --save @cloudscape-design/[email protected]`
1. `npm install --save @cloudscape-design/component-toolkit@^1.0.0-beta.62`

### Step 2: Initialize the AWS IoT Twinmaker source
There are two options to initialize a twinmaker data source:

1. Use the following code to initialize an instance of [@aws-sdk/client-iottwinmaker](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/clients/client-iottwinmaker/index.html).

<Source dark="true" code={`
import { IoTTwinMakerClient } from '@aws-sdk/client-iottwinmaker';
import { initialize } from '@iot-app-kit/source-twinmaker';
const iotTwinMakerClient = new IoTTwinMakerClient({ region: "REGION" });
const { query } = initialize({ iotTwinMakerClient });
`} />

2. Use the following code to initialize an instance of [@aws-sdk/credential-providers](https://www.npmjs.com/package/@aws-sdk/credential-providers).
Replace the credential provider with a provider of your choice.

<Source dark="true" code={`
import { initialize } from '@iot-app-kit/source-iottwinmaker';
import { fromCognitoIdentity } from "@aws-sdk/credential-providers";
// Replace twin-maker-workspace-id with the ID of your AWS IoT TwinMaker workspace, and replace
// REGION with the region of your workspace.
const { query } = initialize('twin-maker-workspace-id', { awsCredentials: fromCognitoIdentity(...), awsRegion: 'REGION' });
`} />

### Step 3: Include the style sheets

The following code shows how to include the stylesheets.

<Source dark="true" code={`
import "@iot-app-kit/components/styles.css";
`} />

### Step 4: Mount the SceneViewer component

The following example explains how to mount the SceneViewer component.

<Source dark="true" code={`
import { initialize, TwinMakerQuery } from '@iot-app-kit/source-iottwinmaker';
import { SceneViewer } from '@iot-app-kit/scene-composer';
import "@iot-app-kit/components/styles.css";
const { query, s3SceneLoader } = initialize( ... );
// Replace scene-id with the ID of your AWS IoT TwinMaker scene in the workspace.
const sceneLoader = s3SceneLoader('scene-id');
const queries: TwinMakerQuery[] = [
{
// Replace entity-id with the ID of your AWS IoT TwinMaker entity in the workspace.
entityId: 'entity-id',
// Replace component-name with the name of the component for your entity.
componentName: 'component-name',
// Replace property-name with the name of the property for your component.
properties: [{ propertyName: 'property-name' }],
},
{
// Replace component-type-id with the ID of your concrete AWS IoT TwinMaker component type in the workspace.
componentTypeId: 'component-type-id',
// Replace property-name with the name of the property for your component type.
properties: [{ propertyName: 'property-name' }],
},
];
const viewport = {
// Replace start-time with the start time to query data from your workspace.
start: new Date('start-time'),
// Replace end-time with the end time to query data from your workspace.
end: new Date('end-time'),
};
// React component example
const MyApp = () => {
return (
<SceneViewer
sceneLoader={sceneLoader}
queries={queries}
viewport={viewport}
/>
);
}
`} />

For more information about [Workspace](https://docs.aws.amazon.com/iot-twinmaker/latest/guide/twinmaker-gs-workspace.html) and [Scenes](https://docs.aws.amazon.com/iot-twinmaker/latest/guide/scenes.html), please visit our guides about [how to get started with AWS IoT Twinmaker](https://docs.aws.amazon.com/iot-twinmaker/latest/guide/twinmaker-gs.html)

For more information about Data source queries, please visit [AWS IoT Twinmaker source documentation page](/iot-app-kit/?path=/docs/data-sources-aws-iot-twinmaker--docs)


### Step 6 (Optional): Mount the VideoPlayer component

The following example explains how to mount the VideoPlayer component.

<Source dark="true" code={`
import { initialize } from '@iot-app-kit/source-iottwinmaker';
import { VideoPlayer } from '@iot-app-kit/react-components';
const videoData = initialize( ... ).videoData({
// Replace entity-id with your AWS IoT TwinMaker entity that has KinesisVideoStream component
entityId: 'entity-id',
// Replace component-name with the name of the component for your entity that has KinesisVideoStreamName property
componentName: 'component-name',
});
// or
const videoData = initialize( ... ).videoData({
// Replace kvs-stream-name with your KinesisVideo stream name
kvsStreamName: 'kvs-stream-name',
});
// Video player for On-Demand playback mode with specified start and end time
const MyVideoOnDemandApp = () => {
return (
<VideoPlayer
videoData={videoData}
// Replace start-time and end-time with the correct time to play the video.
viewport={{ start: new Date('start-time'), end: new Date('end-time') }}
/>
);
}
// Video player for Live playback mode
const MyVideoApp = () => {
return (
<VideoPlayer
videoData={videoData}
viewport={{ duration: '0' }}
/>
);
}
`} />

0 comments on commit 0f64335

Please sign in to comment.