From 71e59be2ad0abcabb9136cf88c3c6c1d16606390 Mon Sep 17 00:00:00 2001 From: Xinyi Xu Date: Thu, 29 Sep 2022 10:09:03 -0700 Subject: [PATCH] doc(TwinMaker): update TwinMaker docs and link them to the main doc (#256) --- README.md | 14 +++++++++ docs/AWSIoTTwinMakerSource.md | 54 +++++++++++++++++------------------ docs/Components.md | 2 ++ docs/SceneViewer.md | 30 +++++++++---------- docs/VideoPlayer.md | 10 +++---- 5 files changed, 63 insertions(+), 47 deletions(-) diff --git a/README.md b/README.md index dfb7be181..1eb6bef12 100644 --- a/README.md +++ b/README.md @@ -25,9 +25,13 @@ IoT Application Kit is a development library for creating web applications to vi * [Status timeline](https://github.com/awslabs/iot-app-kit/tree/main/docs/StatusTimeline.md) * [Resource explorer](https://github.com/awslabs/iot-app-kit/tree/main/docs/ResourceExplorer.md) * [Table](https://github.com/awslabs/iot-app-kit/tree/main/docs/Table.md) +* [Scene Viewer](https://github.com/awslabs/iot-app-kit/blob/main/docs/SceneViewer.md) +* [Video Player](https://github.com/awslabs/iot-app-kit/blob/main/docs/VideoPlayer.md) [AWS IoT SiteWise source](https://github.com/awslabs/iot-app-kit/tree/main/docs/AWSIoTSiteWiseSource.md) - Learn how to connect the IoT App Kit components with AWS IoT SiteWise +[AWS IoT TwinMaker source](https://github.com/awslabs/iot-app-kit/blob/main/docs/AWSIoTTwinMakerSource.md) - Learn how to connect the IoT App Kit components with AWS IoT TwinMaker + [Time series data features](https://github.com/awslabs/iot-app-kit/tree/main/docs/TimeSeriesDataFeatures.md) - Learn about what IoT App Kit does for you when managing time series data around caching, TTLs, buffering, etc. ### For IoT App Kit contributors @@ -62,11 +66,21 @@ The IoT Application Kit mono-repo containing the following packages: [Learn more here](https://github.com/awslabs/iot-app-kit/tree/main/docs/AWSIoTSiteWiseSource.md). +### @iot-app-kit/source-iottwinmaker +`@iot-app-kit/source-iottwinmaker` exposes the AWS IoT TwinMaker source, which enables you to visualize and interact with your [AWS IoT TwinMaker](https://docs.aws.amazon.com/iot-twinmaker/latest/guide/what-is-twinmaker.html) data and digital twins. + +[Learn more here](https://github.com/awslabs/iot-app-kit/blob/main/docs/AWSIoTTwinMakerSource.md). + ### @iot-app-kit/related-table `@iot-app-kit/related-table` is a tree view table component built over `@awsui/components-react` components providing client-side filtering, sorting and pagination with highly performant and optimistic rendering. [Learn more here](https://github.com/awslabs/iot-app-kit/blob/main/packages/related-table/README.md). +### @iot-app-kit/scene-composer +`@iot-app-kit/scene-composer` is a 3D rendering component built over `@react-three/fiber` that renders your digital twin and enables you to interact with it. + +[Learn more here](https://github.com/awslabs/iot-app-kit/blob/main/docs/SceneViewer.md). + ## Security See [CONTRIBUTING](CONTRIBUTING.md#security-issue-notifications) for more information. diff --git a/docs/AWSIoTTwinMakerSource.md b/docs/AWSIoTTwinMakerSource.md index 84092dbba..eb6547b84 100644 --- a/docs/AWSIoTTwinMakerSource.md +++ b/docs/AWSIoTTwinMakerSource.md @@ -104,7 +104,7 @@ const { query } = initialize( ... ); A method that is used to construct the query to process AWS IoT TwinMaker time series data. -- Type: Function +Type: Function - Parameter: `TwinMakerEntityHistoryQuery` | `TwinMakerComponentHistoryQuery` - the inputs used to send request - ReturnType: `TimeQuery` @@ -116,19 +116,19 @@ The query parameters to get the history data for an entity from AWS IoT TwinMake The `entityId` field of the AWS IoT TwinMaker entity to be queried -- Type: String +Type: String `componentName` The `componentName` field of one of the components of the requested entity to be queried -- Type: String +Type: String `properties` One or more properties of the requested component to be queried -- Type: Array +Type: Array Each property contains the following fields: @@ -136,13 +136,13 @@ Each property contains the following fields: The name of the property to be queried. - - Type: String + 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 + Type: String **Query construction example** @@ -162,13 +162,13 @@ The query parameters to get the history data for a component type from AWS IoT T The ID of the AWS IoT TwinMaker component type to be queried -- Type: String +Type: String `properties` One or more properties of the requested component to be queried -- Type: Array +Type: Array Each property contains the following fields: @@ -176,13 +176,13 @@ Each property contains the following fields: The name of the property to be queried. - - Type: String + 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 + Type: String **Query construction example** @@ -207,7 +207,7 @@ import { initialize } from '@iot-app-kit/source-iottwinMaker'; const { s3SceneLoader } = initialize( ... ); ``` -- Type: Function +Type: Function - Parameter: `sceneId` - the ID of the AWS IoT TwinMaker scene to be loaded - ReturnType: `SceneLoader` @@ -219,7 +219,7 @@ The interface of the class to load scene metadata and content. The function to fetch the scene metadata, generate the uri for the scene file and return. -- Type: Function +Type: Function - ReturnType: `Promise` - Resolves with `null` when data is missing to generate a proper uri - Example output: `s3://bucket-name/scene.json` @@ -228,7 +228,7 @@ The function to fetch the scene metadata, generate the uri for the scene file an The function to download scene file or objects specified by the `uri` from S3. -- Type: Function +Type: Function - Parameter: `uri` - the uri of the object to be downloaded from S3. - ReturnType: `Promise | null` - Returns `null` when the `uri` is invalids @@ -247,7 +247,7 @@ import { initialize } from '@iot-app-kit/source-iottwinMaker'; const { videoData } = initialize( ... ); ``` -- Type: Function +Type: Function - Parameter: `videoDataProps` - this is of type `VideoDataProps` which provides information about the video stream and related AWS IoT TwinMaker component - ReturnType: `VideoData` @@ -257,31 +257,31 @@ const { videoData } = initialize( ... ); The video stream name of the desired Kinesis Video Streams -- Type: String +Type: String `entityId` The `entityId` field of the AWS IoT TwinMaker entity having the video component -- Type: String +Type: String `componentName` The `componentName` field of one of the video components of the referenced entity -- Type: String +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 +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 +Type: String ### `VideoData` @@ -291,7 +291,7 @@ The interface of the class to fetch the video metadata and handle the video sour The function to fetch the the HTTP Live Streaming (HLS) URL for the video stream. -- Type: Function +Type: Function - ReturnType: `Promise` - Resolves with `undefined` when video stream information is not found - Example output: `https://example.com/sample-video.m3u8` @@ -300,12 +300,12 @@ The function to fetch the the HTTP Live Streaming (HLS) URL for the video stream The function to get the list of available time ranges for the video streams. -- Type: Function +Type: Function - Parameter: - `startTime` - intended start time for the video playback - - Type: Date + Type: Date - `endTime` - intended end time for the video playback - - Type: Date + 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 @@ -316,19 +316,19 @@ The function to get the list of available time ranges for the video streams. The function to trigger the video upload request from edge to Kinesis Video Streams for `LIVE` playback. -- Type: Function +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 +Type: Function - Parameter: - `startTimestamp` - intended start timestamp for the video upload request - - Type: String + Type: String - `endTimestamp` - intended end timestamp for the video upload request - - Type: String + Type: String - ReturnType: `Promise` --- diff --git a/docs/Components.md b/docs/Components.md index 2660449cc..f171ed7ef 100644 --- a/docs/Components.md +++ b/docs/Components.md @@ -10,4 +10,6 @@ IoT App Kit provides the following components that you can use to interact with * [Table](https://github.com/awslabs/iot-app-kit/tree/main/docs/Table.md) * [Status timeline](https://github.com/awslabs/iot-app-kit/tree/main/docs/StatusTimeline.md) * [Resource explorer](https://github.com/awslabs/iot-app-kit/tree/main/docs/ResourceExplorer.md) +* [Scene Viewer](https://github.com/awslabs/iot-app-kit/blob/main/docs/SceneViewer.md) (React component only) +* [Video Player](https://github.com/awslabs/iot-app-kit/blob/main/docs/VideoPlayer.md) (React component only) diff --git a/docs/SceneViewer.md b/docs/SceneViewer.md index a0527bf75..d7b2c1b60 100644 --- a/docs/SceneViewer.md +++ b/docs/SceneViewer.md @@ -6,7 +6,7 @@ The SceneViewer component allows you to render a specified [AWS IoT TwinMaker sc 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. +There is sample code in [examples/react-app](https://github.com/awslabs/iot-app-kit/tree/main/examples/react-app) that shows how to use this component in detail. ### Basic React component example @@ -31,13 +31,13 @@ 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` +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 +Type: String ### `dataStreams` @@ -45,13 +45,13 @@ The class to load scene metadata and content. 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` +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` +Type: `TimeQuery[]` defined in `@iot-app-kit/core` This property is used together with `viewport`. @@ -59,7 +59,7 @@ This property is used together with `viewport`. (Optional) Specifies the window over which to query the data. -- Type: `Viewport` defined in `@iot-app-kit/core` +Type: `Viewport` defined in `@iot-app-kit/core` This property is used together with `queires`. @@ -67,7 +67,7 @@ This property is used together with `queires`. (Optional) A map from data binding template names to the actual values to be used by the scene. -- Type: `Record` +Type: `Record` Example: @@ -85,7 +85,7 @@ Then the Tag widget will use the data from `real-entity-1` to change its visual. Empty information will be sent when deselection happens. -- Type: `SelectionChangedEventCallback` defined in `@iot-app-kit/scene-composer` +Type: `SelectionChangedEventCallback` defined in `@iot-app-kit/scene-composer` ### `onWidgetClick` @@ -93,7 +93,7 @@ Empty information will be sent when deselection happens. Currently, only Tag widget will trigger this callback. -- Type: `WidgetClickEventCallback` defined in `@iot-app-kit/scene-composer` +Type: `WidgetClickEventCallback` defined in `@iot-app-kit/scene-composer` ### `selectedDataBinding` @@ -104,7 +104,7 @@ 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>` +Type: `Record<'entityId' | 'componentName', string>` ### `activeCamera` @@ -112,7 +112,7 @@ When there is no matching Tag widget found, the currently selected node will be 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 +Type: String ### `config` @@ -120,15 +120,15 @@ When this is not found or not set the default initial camera is used. When `sele - `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) + (Optional) 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 + Type: Object - `locale` - The language for the texts displayed in the component. Default to `en-US`. + (Optional) 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 + Type: String diff --git a/docs/VideoPlayer.md b/docs/VideoPlayer.md index de7c5f49e..a0d45571f 100644 --- a/docs/VideoPlayer.md +++ b/docs/VideoPlayer.md @@ -7,7 +7,7 @@ The VideoPlayer component allows you to stream a video from the Kinesis Video St ## 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. +There is sample code in [examples/react-app](https://github.com/awslabs/iot-app-kit/tree/main/examples/react-app) that shows how to use this component in detail. ### Basic React component example @@ -44,13 +44,13 @@ The class to fetch the video metadata and handle the video source related operat **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` +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` +Type: `Viewport` defined in `@iot-app-kit/core` Example: @@ -72,7 +72,7 @@ The RequestVideoUpload component allows you to send a request to upload video fr ## 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. +There is sample code in [examples/react-app](https://github.com/awslabs/iot-app-kit/tree/main/examples/react-app) that shows how to use this component in detail. ### Basic React component example @@ -99,4 +99,4 @@ The RequestVideoUpload component contains the following properties that you can The class to fetch the video metadata and handle the video source related operations. -- Type: `VideoData` defined in `@iot-app-kit/source-iottwinmaker` +Type: `VideoData` defined in `@iot-app-kit/source-iottwinmaker`