From 45efae08543794232d3a396555d7a33e617d0724 Mon Sep 17 00:00:00 2001 From: Xinyi Xu Date: Thu, 22 Sep 2022 13:33:12 -0700 Subject: [PATCH] Add documentation (#116) * add TM data source query documentation * scene loader documentation * SceneViewer documentation * fix build * VideoData Documentation * feat(TwinMaker Documentation) - Documentation for VideoData * feat(TwinMaker Documentation) - Documentation for VideoPlayer Co-authored-by: Mukesh Sahay --- docs/AWSIoTTwinMakerSource.md | 334 ++++++++++++++++++ docs/SceneViewer.md | 134 +++++++ docs/VideoPlayer.md | 102 ++++++ .../scene-composer/src/SceneViewer.spec.tsx | 12 +- packages/scene-composer/src/SceneViewer.tsx | 2 +- .../src/interfaces/sceneViewer.ts | 6 +- .../source-iottwinmaker/src/initialize.ts | 53 ++- 7 files changed, 626 insertions(+), 17 deletions(-) create mode 100644 docs/AWSIoTTwinMakerSource.md create mode 100644 docs/SceneViewer.md create mode 100644 docs/VideoPlayer.md diff --git a/docs/AWSIoTTwinMakerSource.md b/docs/AWSIoTTwinMakerSource.md new file mode 100644 index 000000000..84092dbba --- /dev/null +++ b/docs/AWSIoTTwinMakerSource.md @@ -0,0 +1,334 @@ +# AWS IoT TwinMaker source + +The AWS IoT TwinMaker source enables you to visualize your [AWS IoT TwinMaker](https://docs.aws.amazon.com/iot-twinmaker/latest/guide/what-is-twinmaker.html) data and digital twins. + +You can follow [AWS IoT TwinMaker Getting Started](https://github.com/aws-samples/aws-iot-twinmaker-samples) to setup a sample TwinMaker workspace. + +## Setting up the AWS IoT TwinMaker source + +1. Install the dependency using npm: + +```sh +npm install --save @iot-app-kit/source-iottwinmaker +``` + +2. Choose one of the following to initialize the AWS IoT TwinMaker source: + + 1. Initialize with aws client instances. + + - Required aws clients: + + [@aws-sdk/client-iottwinmaker](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/clients/client-iottwinmaker/index.html) + + [@aws-sdk/client-iotsitewise](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/clients/client-iotsitewise/index.html) + + [@aws-sdk/client-kinesis-video](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/clients/client-kinesis-video/index.html) + + [@aws-sdk/client-kinesis-video-archived-media](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/clients/client-kinesis-video-archived-media/index.html) + + [@aws-sdk/client-s3](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/clients/client-s3/index.html) + + - Sample code: + + ```ts + import { IoTTwinMakerClient } from '@aws-sdk/client-iottwinmaker'; + import { IoTSiteWiseClient } from '@aws-sdk/client-iotsitewise'; + import { KinesisVideoClient } from '@aws-sdk/client-kinesis-video'; + import { KinesisVideoArchivedMediaClient } from '@aws-sdk/client-kinesis-video-archived-media'; + import { S3Client } from '@aws-sdk/client-s3'; + + import { initialize } from '@iot-app-kit/source-iottwinmaker'; + + const iotTwinMakerClient = new IoTTwinMakerClient({ ... }); + const iotSiteWiseClient = new IoTSiteWiseClient({ ... }); + const kinesisVideoClient = new KinesisVideoClient({ ... }); + const kinesisVideoArchivedMediaClient = new KinesisVideoArchivedMediaClient({ ... }); + const s3Client = new S3Client({ ... }); + + const { query } = initialize('twin-maker-workspace-id', { + iotSiteWiseClient, + iotTwinMakerClient, + kinesisVideoClient, + kinesisVideoArchivedMediaClient, + s3Client, + }); + ``` + + 2. Initialize with aws region and [Credentials](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/interfaces/_aws_sdk_types.credentials-1.html) or [CredentialProvider](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/modules/_aws_sdk_types.html#credentialprovider-1) + + - [@aws-sdk/credential-providers](https://www.npmjs.com/package/@aws-sdk/credential-providers) can be used to create credential providers. + + - Sample code: + + ```ts + import { fromCognitoIdentity } from "@aws-sdk/credential-providers"; + import { initialize } from '@iot-app-kit/source-iottwinmaker'; + + const { query } = initialize('twin-maker-workspace-id', { awsCredentials: fromCognitoIdentity(...), awsRegion: 'REGION' }); + ``` + + 3. Initialize with a combination of previous options: + + - Sample code: + + ```ts + import { IoTTwinMakerClient } from '@aws-sdk/client-iottwinmaker'; + import { fromCognitoIdentity } from "@aws-sdk/credential-providers"; + + import { initialize } from '@iot-app-kit/source-iottwinmaker'; + + const iotTwinMakerClient = new IoTTwinMakerClient({ ... }); + + const { query } = initialize('twin-maker-workspace-id', { + awsCredentials: fromCognitoIdentity(...), + awsRegion: 'REGION', + iotTwinMakerClient, + }); + ``` + +--- + +## `query` + +The queries that you can use to fetch AWS IoT TwinMaker data. + +Queries are available upon initialization of the AWS IoT TwinMaker source. + +```ts +import { initialize } from '@iot-app-kit/source-iottwinMaker'; + +const { query } = initialize( ... ); +``` + +### `timeSeriesData` + +A method that is used to construct the query to process AWS IoT TwinMaker time series data. + +- Type: Function +- Parameter: `TwinMakerEntityHistoryQuery` | `TwinMakerComponentHistoryQuery` - the inputs used to send request +- ReturnType: `TimeQuery` + +#### `TwinMakerEntityHistoryQuery` + +The query parameters to get the history data for an entity from AWS IoT TwinMaker. + +`entityId` + +The `entityId` field of the AWS IoT TwinMaker entity to be queried + +- Type: String + +`componentName` + +The `componentName` field of one of the components of the requested entity to be queried + +- Type: String + +`properties` + +One or more properties of the requested component to be queried + +- Type: Array + +Each property contains the following fields: + +- `propertyName` + + The name of the property to be queried. + + - Type: String + +- `refId` + + (Optional) The reference ID of the style settings. IoT App Kit applies the style settings to the property associated with the reference ID. Every component has different style settings. + + - Type: String + +**Query construction example** + +```ts +query.timeSeriesData({ + entityId: 'entity-id', + componentName: 'component-name', + properties: [{ propertyName: 'property-name', refId: 'my-property-ref' }], +}); +``` + +#### `TwinMakerComponentHistoryQuery` + +The query parameters to get the history data for a component type from AWS IoT TwinMaker. + +`componentTypeId` + +The ID of the AWS IoT TwinMaker component type to be queried + +- Type: String + +`properties` + +One or more properties of the requested component to be queried + +- Type: Array + +Each property contains the following fields: + +- `propertyName` + + The name of the property to be queried. + + - Type: String + +- `refId` + + (Optional) The reference ID of the style settings. IoT App Kit applies the style settings to the property associated with the reference ID. Every component has different style settings. + + - Type: String + +**Query construction example** + +```ts +query.timeSeriesData({ + componentTypeId: 'component-type-id', + properties: [{ propertyName: 'property-name', refId: 'my-property-ref' }], +}); +``` + +--- + +## `s3SceneLoader` + +The loader class to fetch the AWS IoT TwinMaker scene metadata and content that's stored in S3. + +This class is primarily to be utilized by the `SceneView` component from `iot-app-kit/scene-composer` package, and is available upon initialization of the AWS IoT TwinMaker source. + +```ts +import { initialize } from '@iot-app-kit/source-iottwinMaker'; + +const { s3SceneLoader } = initialize( ... ); +``` + +- Type: Function +- Parameter: `sceneId` - the ID of the AWS IoT TwinMaker scene to be loaded +- ReturnType: `SceneLoader` + +### `SceneLoader` + +The interface of the class to load scene metadata and content. + +#### `getSceneUri` + +The function to fetch the scene metadata, generate the uri for the scene file and return. + +- Type: Function +- ReturnType: `Promise` + - Resolves with `null` when data is missing to generate a proper uri + - Example output: `s3://bucket-name/scene.json` + +#### `getSceneObject` + +The function to download scene file or objects specified by the `uri` from S3. + +- Type: Function +- Parameter: `uri` - the uri of the object to be downloaded from S3. +- ReturnType: `Promise | null` + - Returns `null` when the `uri` is invalids + +--- + +## `videoData` + +The class to fetch the metadata for the video stream coming directly from the Kinesis Video Streams or as defined in the AWS IoT TwinMaker entity. + +This class is primarily to be utilized by the `VideoPlayer` component from `iot-app-kit/react-components` package, and is available upon initialization of the AWS IoT TwinMaker source. + +```ts +import { initialize } from '@iot-app-kit/source-iottwinMaker'; + +const { videoData } = initialize( ... ); +``` + +- Type: Function +- Parameter: `videoDataProps` - this is of type `VideoDataProps` which provides information about the video stream and related AWS IoT TwinMaker component +- ReturnType: `VideoData` + +### `VideoDataProps` + +`kvsStreamName` + +The video stream name of the desired Kinesis Video Streams + +- Type: String + +`entityId` + +The `entityId` field of the AWS IoT TwinMaker entity having the video component + +- Type: String + +`componentName` + +The `componentName` field of one of the video components of the referenced entity + +- Type: String + +`sitewiseAssetId` + +The value of the property `sitewiseAssetId` of the AWS IoT SiteWise asset associated with the AWS IoT TwinMaker video component + +- Type: String + +`videoUploadRequestPropertyId` + +The value of the property `VideoUploadRequest` of the AWS IoT SiteWise asset associated with the AWS IoT TwinMaker video component + +- Type: String + +### `VideoData` + +The interface of the class to fetch the video metadata and handle the video source related operations. + +#### `getKvsStreamSrc` + +The function to fetch the the HTTP Live Streaming (HLS) URL for the video stream. + +- Type: Function +- ReturnType: `Promise` + - Resolves with `undefined` when video stream information is not found + - Example output: `https://example.com/sample-video.m3u8` + +#### `getAvailableTimeRanges` + +The function to get the list of available time ranges for the video streams. + +- Type: Function +- Parameter: + - `startTime` - intended start time for the video playback + - Type: Date + - `endTime` - intended end time for the video playback + - Type: Date +- ReturnType: `Promise<[{ start: number; end: number; src: string }[], { start: number; end: number }[]] | undefined>` + - Returns two arrays + - First with the information of all the video sources available in Kinesis Video Streams for playback + - Second with the list of start and end times when the video is captured and is available on the edge + - Returns `undefined` when an invalid AWS IoT TwinMaker component is referenced in the VideoData + +#### `triggerLiveVideoUpload` + +The function to trigger the video upload request from edge to Kinesis Video Streams for `LIVE` playback. + +- Type: Function +- ReturnType: `Promise` + +#### `triggerOnDemandVideoUploadRequest` + +The function to trigger the video upload request from edge to Kinesis Video Streams for a specified time range. + +- Type: Function +- Parameter: + - `startTimestamp` - intended start timestamp for the video upload request + - Type: String + - `endTimestamp` - intended end timestamp for the video upload request + - Type: String +- ReturnType: `Promise` + +--- diff --git a/docs/SceneViewer.md b/docs/SceneViewer.md new file mode 100644 index 000000000..a0527bf75 --- /dev/null +++ b/docs/SceneViewer.md @@ -0,0 +1,134 @@ +# Scene Viewer + +The SceneViewer component allows you to render a specified [AWS IoT TwinMaker scene](https://docs.aws.amazon.com/iot-twinmaker/latest/guide/scenes.html) for viewing experience. + +## Setup + +The SceneViewer component renders assets including `.svg` and `.hdr` files. You will need to configure proper loader like [file-loader](https://v4.webpack.js.org/loaders/file-loader/) for your application. + +There is sample code in [examples/react-app](https://github.com/awslabs/iot-app-kit/tree/main/sample-app/examples/react-app) that shows how to use this component in detail. + +### Basic React component example + +```tsx +import { initialize } from '@iot-app-kit/source-iottwinmaker'; +import { SceneViewer } from '@iot-app-kit/scene-composer'; + +const sceneLoader = initialize({ ... }).s3SceneLoader('scene-id'); + + +``` + +## Properties + +The SceneViewer component contains the following properties that you can customize. + +### `sceneLoader` + +The class to load scene metadata and content. + +**Note: When a new instance of this object is passed in, the SceneView will trigger a new loading of the whole scene. Therefore, do not recreate this object when not needed.** + +- Type: `SceneLoader` defined in `@iot-app-kit/source-iottwinmaker` + +### `sceneComposerId` + +(Optinal) An unique id for one instance of the SceneViewer component. If not provided, an uuid will be auto generated. + +- Type: String + +### `dataStreams` + +(Optional) The data used by the viewer to change the visuals of the scene objects. + +The `meta` field of each stream is required to contain values for keys `entityId`, `componentName` and `propertyName`. The scene objects with the matching meta values will use the corresponding stream. + +- Type: `DataStream[]` defined in `@iot-app-kit/core` + +### `queries` + +(Optional) Selects what data to be fetched. Learn more about queries, see [Core](https://github.com/awslabs/iot-app-kit/tree/main/docs/Core.md). + +- Type: `TimeQuery[]` defined in `@iot-app-kit/core` + +This property is used together with `viewport`. + +### `viewport` + +(Optional) Specifies the window over which to query the data. + +- Type: `Viewport` defined in `@iot-app-kit/core` + +This property is used together with `queires`. + +### `dataBindingTemplate` + +(Optional) A map from data binding template names to the actual values to be used by the scene. + +- Type: `Record` + +Example: + +With a template named `sel_entity` defined in your scene and bind to a Tag widget, you can pass the following as `dataBindingTemplate` +```ts +{ + 'sel_entity': 'real-entity-1' +} +``` +Then the Tag widget will use the data from `real-entity-1` to change its visual. + +### `onSelectionChanged` + +(Optional) A callback that will be triggered when the selected node in the scene is changed. The information about the selection node will be passed out. + +Empty information will be sent when deselection happens. + +- Type: `SelectionChangedEventCallback` defined in `@iot-app-kit/scene-composer` + +### `onWidgetClick` + +(Optional) A callback that will be triggered when a widget in the scene is clicked. The information about the clicked widget will be passed out. + +Currently, only Tag widget will trigger this callback. + +- Type: `WidgetClickEventCallback` defined in `@iot-app-kit/scene-composer` + +### `selectedDataBinding` + +(Optional) Set the selected node to be the Tag widget with matching `entityId` and `componentName`, +and move the camera target to it. + +When the selectedDataBinding value is undefined, no action will be taken. + +When there is no matching Tag widget found, the currently selected node will be deselected. + +- Type: `Record<'entityId' | 'componentName', string>` + +### `activeCamera` + +(Optional) Sets the camera to view from by Camera name. + +When this is not found or not set the default initial camera is used. When `selectedDataBinding` is set this is ignored in favor of focusing on the selected item. + +- Type: String + +### `config` + +(Optional) The configurations of the component + +- `dracoDecoder` + + The configurations for a draco decoder. More information can be found [here](https://docs.aws.amazon.com/iot-twinmaker/latest/guide/scenes-before-starting.html) + + - Type: Object + +- `locale` + + The language for the texts displayed in the component. Default to `en-US`. + + The supported locales can be found under `packages/scene-composer/translations` folder. + + - Type: String + diff --git a/docs/VideoPlayer.md b/docs/VideoPlayer.md new file mode 100644 index 000000000..de7c5f49e --- /dev/null +++ b/docs/VideoPlayer.md @@ -0,0 +1,102 @@ +# Video Player + +The VideoPlayer component allows you to stream a video from the Kinesis Video Streams. It supports the following configuration: + +- Simple Mode: Stream the video from the Kinesis Video Streams using the provided stream name +- AWS IoT TwinMaker Mode: Video player is provided with the `entityId` and `componentName` from an AWS IoT TwinMaker workspace. Video player determines the required information using provided inputs and streams the video. Details can be found at [AWS IoT TwinMaker video integration](https://docs.aws.amazon.com/iot-twinmaker/latest/guide/video-integration.html). + +## Setup + +There is sample code in [examples/react-app](https://github.com/awslabs/iot-app-kit/tree/main/sample-app/examples/react-app) that shows how to use this component in detail. + +### Basic React component example + +```tsx +import { initialize } from '@iot-app-kit/source-iottwinmaker'; +import { VideoPlayer } from '@iot-app-kit/react-components'; + +const videoData = initialize({ ... }).videoData({ + entityId: 'twinmakerEntityId', + componentName: 'twinmakerComponentName', + kvsStreamName: 'sample-kvs-stream', +}); + +// Video player for On-Demand playback mode with specified start and end time + + +// Video player for Live playback mode + +``` + +## Properties + +The VideoPlayer component contains the following properties that you can customize. + +### `videoData` + +The class to fetch the video metadata and handle the video source related operations. + +**Note: When a new instance of this object is passed in, the VideoPlayer will trigger a new loading of the video stream. Therefore, do not recreate this object when not needed.** + +- Type: `VideoData` defined in `@iot-app-kit/source-iottwinmaker` + +### `viewport` + +Specifies the time range for video playback. + +- Type: `Viewport` defined in `@iot-app-kit/core` + +Example: + +```tsx +// On-Demand mode with specific start and end times +const startTime = new Date(1661470165); +const endTime = new Date(1661471180); +const viewport = {{ start: startTime, end: endTime }}; + +// Live mode to play video from now +const viewport = {{ duration: '0' }}; +``` + +--- + +# Video Upload Request + +The RequestVideoUpload component allows you to send a request to upload video from edge to the Kinesis Video Streams. This is used in case of an Edge Video component from an AWS IoT TwinMaker workspace where the video can be available on the edge, but not available for streaming. The newly uploaded video can be streamed by the `VideoPlayer` component from Kinesis Video Streams once available. More details about the Edge Video component can be found [here](https://docs.aws.amazon.com/iot-twinmaker/latest/guide/video-integration.html). + +## Setup + +There is sample code in [examples/react-app](https://github.com/awslabs/iot-app-kit/tree/main/sample-app/examples/react-app) that shows how to use this component in detail. + +### Basic React component example + +```tsx +import { initialize } from '@iot-app-kit/source-iottwinmaker'; +import { RequestVideoUpload } from '@iot-app-kit/react-components'; + +const videoData = initialize({ ... }).videoData({ + entityId: 'twinmakerEntityId', + componentName: 'twinmakerEdgeVideoComponentName', + kvsStreamName: 'sample-kvs-stream', +}); + + +``` + +## Properties + +The RequestVideoUpload component contains the following properties that you can customize. + +### `videoData` + +The class to fetch the video metadata and handle the video source related operations. + +- Type: `VideoData` defined in `@iot-app-kit/source-iottwinmaker` diff --git a/packages/scene-composer/src/SceneViewer.spec.tsx b/packages/scene-composer/src/SceneViewer.spec.tsx index 2d07f6897..e70e19f62 100644 --- a/packages/scene-composer/src/SceneViewer.spec.tsx +++ b/packages/scene-composer/src/SceneViewer.spec.tsx @@ -36,7 +36,7 @@ describe('SceneViewer', () => { it('should render correctly', async () => { let container; act(() => { - container = renderer.create(); + container = renderer.create(); }); expect(container).toMatchSnapshot(); @@ -49,9 +49,7 @@ describe('SceneViewer', () => { let container; act(() => { - container = renderer.create( - , - ); + container = renderer.create(); }); expect(mockSceneComposerApi.findSceneNodeRefBy).toBeCalledTimes(1); @@ -62,7 +60,7 @@ describe('SceneViewer', () => { expect(mockSceneComposerApi.setSelectedSceneNodeRef).toBeCalledWith(mockNodeRef[0]); // not re-setting camera with same data binding values - container.update(); + container.update(); expect(mockSceneComposerApi.findSceneNodeRefBy).toBeCalledTimes(1); expect(mockSceneComposerApi.setCameraTarget).toBeCalledTimes(1); @@ -74,9 +72,7 @@ describe('SceneViewer', () => { let container; act(() => { - container = renderer.create( - , - ); + container = renderer.create(); }); expect(mockSceneComposerApi.findSceneNodeRefBy).toBeCalledTimes(1); diff --git a/packages/scene-composer/src/SceneViewer.tsx b/packages/scene-composer/src/SceneViewer.tsx index c50aa6610..b12642681 100644 --- a/packages/scene-composer/src/SceneViewer.tsx +++ b/packages/scene-composer/src/SceneViewer.tsx @@ -51,7 +51,7 @@ export const SceneViewer: React.FC = ({ sceneComposerId, confi ; + selectedDataBinding?: Record<'entityId' | 'componentName', string>; /** * Sets the camera to view from by Camera name. diff --git a/packages/source-iottwinmaker/src/initialize.ts b/packages/source-iottwinmaker/src/initialize.ts index fafbdde98..41ca112c9 100644 --- a/packages/source-iottwinmaker/src/initialize.ts +++ b/packages/source-iottwinmaker/src/initialize.ts @@ -15,30 +15,75 @@ import { TwinMakerTimeSeriesDataProvider } from './time-series-data/provider'; import { createDataSource } from './time-series-data/data-source'; import { TwinMakerMetadataModule } from './metadata-module/TwinMakerMetadataModule'; +/** + * The authInput interface with pre-configured aws client instances. + */ type IoTAppKitInitAuthInputs = { + /** + * The pre-configured IoT SiteWise client + */ iotSiteWiseClient: IoTSiteWiseClient; + /** + * The pre-configured IoT TwinMaker client + */ iotTwinMakerClient: IoTTwinMakerClient; + /** + * The pre-configured KinesisVideo client + */ kinesisVideoClient: KinesisVideoClient; + /** + * The pre-configured KinesisVideoArchivedMedia client + */ kinesisVideoArchivedMediaClient: KinesisVideoArchivedMediaClient; + /** + * The pre-configured S3 client + */ s3Client: S3Client; }; + +/** + * The authInput interface with credential/credentialProvider, region, and optional aws client instances. + */ type IoTAppKitInitAuthInputsWithCred = { + /** + * AWS credentials or credential provider for creating aws clients that are not passed in + */ awsCredentials: Credentials | CredentialProvider; + /** + * AWS region for creating aws clients that are not passed in, i.e. us-east-1 + */ awsRegion: string; + /** + * The endpoint to be used by the IoT TwinMaker client (https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/clients/client-iottwinmaker/interfaces/iottwinmakerclientconfig.html#endpointhttps://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/clients/client-iottwinmaker/interfaces/iottwinmakerclientconfig.html#endpoint) + */ tmEndpoint?: string; + /** + * The pre-configured IoT SiteWise client + */ iotSiteWiseClient?: IoTSiteWiseClient; + /** + * The pre-configured IoT TwinMaker client + */ iotTwinMakerClient?: IoTTwinMakerClient; + /** + * The pre-configured KinesisVideo client + */ kinesisVideoClient?: KinesisVideoClient; + /** + * The pre-configured KinesisVideoArchivedMedia client + */ kinesisVideoArchivedMediaClient?: KinesisVideoArchivedMediaClient; + /** + * The pre-configured S3 client + */ s3Client?: S3Client; }; /** - * Initialize IoT App Kit + * Initialize IoT App Kit TwinMaker data source * - * @param awsCredentials - https://www.npmjs.com/package/@aws-sdk/credential-providers - * @param awsRegion - Region for AWS based data sources to point towards, i.e. us-east-1 - * @param tmEndpoint - the endpoint to be used by the TwinMaker client + * @param workspaceId - the workspaceId of a TwinMaker workspace that this data source will fetch data from + * @param authInput - the set of inputs to get aws client instances ready */ export const initialize = ( workspaceId: string,