initial automated checkin

GA_information_management/digital_twin.md

@@ -0,0 +1,39 @@
+---
+
+copyright:
+  years: 2016, 2017
+lastupdated: "2017-05-02"
+
+---
+
+{:new_window: target="\_blank"}
+{:shortdesc: .shortdesc}
+{:screen: .screen}
+{:codeblock: .codeblock}
+{:pre: .pre}
+
+# Digital twins
+{: #digital_twin}
+
+A digital twin is any digital representation of a device or system and how it behaves within its environment. IBM Watson IoT Platform is solving this problem with the introduction of ‘Device Twins’ and ‘Asset Twins’.  
+{: shortdesc}
+
+Device Twins and Asset Twins can help you:
+- Provide your application developers with consistent interfaces to access event-driven device data in a REST-like manner.
+- Normalize data from devices of different makes or models that publish data in different formats.
+- Combine event data from several different device types to model any given IoT thing.
+
+With Watson IoT Platform you can realize the digital twin concept using:
+- Application Interfaces/Logical Interfaces
+- Device type meta data
+- Device instance meta data
+- Thing instance metadata (API)
+- Device management (unclear how this works with interfaces)
+
+## Device twin  
+{: device_twin}  
+A device twin is a logical model of the properties and events coming from a particular sensor/device. Once defined and instantiated, it provides a consistent means of interacting with a device in a REST-like manner. Because the models can be shared by multiple devices of different makes and models, the IoT application is now insulated from variability and change within the device ecosystem.
+
+## Asset twin  
+{: #asset_twin}  
+An Asset Twin lets you take this concept one step further.  Now you can model higher level ‘things’ that group together sensors and devices into a single entity for a developer to interact with.  For example your Asset Twin might represent a class of automobile that in turn represents hundreds of underlying sensors monitoring the drivetrain, suspension, & fuel systems.  Now let’s say an IoT based fleet management system called on the state & properties of the automobile Asset Twin, it has a simple and consistent way to monitor all its vehicles regardless of make and model.

GA_information_management/ga_im_active_draft.md

@@ -0,0 +1,148 @@
+---
+
+copyright:
+  years: 2016, 2017
+lastupdated: "2017-05-22"
+
+---
+
+{:new_window: target="\_blank"}
+{:shortdesc: .shortdesc}
+{:screen: .screen}
+{:codeblock: .codeblock}
+{:pre: .pre}
+
+
+# Draft and active versions of resources
+{: #draft_active_resources}
+
+There can be two versions of a resource, a draft version and an active version. When you create a resource, that resource is created as a draft version. The draft version is a working copy of your resource that you can query, update and delete directly by using APIs. Create an active version of a draft resource by activating either a draft device type or a draft logical interface which references that resource.
+{: shortdesc}
+
+To differentiate between draft and active resources when using REST APIs, the prefix *draft/* is used to identify resources that are in a draft state.
+
+The following example retrieves metadata for a draft schema definition with a specified id:
+
+```
+GET /api/v0002/draft/schemas/{schemaId}
+```
+The following example retrieves metadata for an active schema definition with a specified id:
+```
+GET /api/v0002/schemas/{schemaId}
+```
+*Note:* The identifier remains the same for the draft and active version of a given resource.
+
+You can activate only a draft device type or a draft logical interface resource. To activate other resources, for example schemas, you must activate a drafter device type or draft logical interface which references that resource.
+
+To activate a draft device type or a draft logical interface resource, complete the following steps as part of a PATCH request:
+1. Perform a **validation-configuration** operation against a draft version of the device type or logical interface resource to ensure that the associated metadata is valid. If the metadata is invalid, a list of issues is returned in the body of the response.
+2. Perform an **activate-configuration** operation against the validated draft version of the device type or logical interface resource to activate that resource and its associated metadata.
+
+The following example shows a PATCH request where a **validation-configuration** operation is performed against a draft version of a device type that is called "TemperatureSensor":  
+```
+PATCH /api/v0002/draft/device/types/TemperatureSensor
+```
+where the payload of the PATCH body contains the following content:
+```
+  {
+    "operation": "validate-configuration"
+  }
+```
+
+The following example shows an unsuccessful response to the PATCH request:
+```
+{
+"message": "CUDIM0303I: State update configuration for Device Type 'TemperatureSensor' is not valid.",
+"details": {
+  "id": "CUDIM0303I",
+  "properties": [
+    "Device Type",
+    "TemperatureSensor"
+  ]
+},
+"failures": [
+  {
+    "message": "CUDVS0301E: The device type 'TemperatureSensor' does not have any mappings defined for it",
+    "details": {
+      "id": "CUDVS0301E",
+      "properties": [
+        "TemperatureSensor"
+      ]
+    }
+  }
+]
+}
+
+```
+
+
+The following example shows a PATCH request where a **activate-configuration** operation is performed against the validated draft version of a device type that is called "TemperatureSensor" and the associated metadata.  An active version of a resource is read-only.
+
+```
+PATCH /api/v0002/draft/device/types/TemperatureSensor
+```
+where the payload of the PATCH body contains the following content:
+```
+  {
+    "operation": "activate-configuration"
+  }
+```
+
+The following example shows a successful response to the PATCH request:
+```
+{
+  "message": "CUDIM0300I: State update configuration for Device Type 'TemperatureSensor' has been successfully submitted for activation.",
+  "details": {
+    "id": "CUDIM0300I",
+    "properties": [
+      "Device Type",
+      "TemperatureSensor"
+    ]
+  },
+  "failures": []
+}
+```
+
+Use the **list-differences** operation to return a list of the differences between the active and draft configuration for a logical interface or device type resource. The **list-differences** operation must be performed against the draft version of a logical interface and device type. The following example shows a PATCH request against a draft version of a device type:
+```
+PATCH /api/v0002/draft/device/types/TemperatureSensor
+```
+where the payload of the PATCH body contains the following content:
+```
+  {
+    "operation": "list-differences"
+  }
+```
+
+Use the **deactivate-configuration** operation to remove the active configuration that is associated with a resource. The deactivate-configuration operation can only be performed against the active version of a logical interface and device type.   The following example shows a PATCH request against an active version of a device type:
+```
+PATCH /api/v0002/device/types/TemperatureSensor
+```
+where the payload of the PATCH body contains the following content:
+```
+  {
+    "operation": "deactivate-configurations"
+  }
+```
+The following example shows a successful response to the PATCH request:
+```
+{
+  "message": "CUDIM0305I: State update configuration for Device Type 'TemperatureSensor' has been successfully submitted for deactivation.",
+  "details": {
+    "id": "CUDIM0305I",
+    "properties": [
+      "Device Type",
+      "TemperatureSensor"
+    ]
+  },
+  "failures": []
+}
+
+```
+*Notes:*
+- If you delete a device type resource, the state of any existing instances of that device type are deleted.
+- An active resource is read only. You can filter and sort draft and active resources by using query parameters.
+- You can activate only logical interfaces and device types directly by using APIs. Other resources, for example schemas, physical interfaces, and event types are activated if they are referenced by a logical interface or device type that is made active.  If you activate a draft schema resource, the logical interface and device types that reference that schema are automatically updated.
+- You must perform the **activate-configuration** operation against a draft version of a logical interface before any state is generated for device types that are associated with that logical interface.
+
+T

GA_information_management/ga_im_definitions.md

@@ -0,0 +1,54 @@
+---
+
+copyright:
+  years: 2016, 2017
+lastupdated: "2017-05-22"
+
+---
+
+{:new_window: target="\_blank"}
+{:shortdesc: .shortdesc}
+{:screen: .screen}
+{:codeblock: .codeblock}
+{:pre: .pre}
+
+
+# Definitions and resources
+{: #definitions_resources}
+
+The following diagram illustrates the logical mapping between devices and applications on {{site.data.keyword.iot_short_notm}} when using logical interfaces.
+
+![The logical mapping between a device and an application on {{site.data.keyword.iot_short_notm}}.](images/ga_im_resources.svg "The mapping between devices, things, and applications on {{site.data.keyword.iot_short_notm}}")
+
+## Concepts
+
+Concepts                        | Description       
+------------- | ------------- | -------------  
+Event | Events are the mechanism by which devices publish data to {{site.data.keyword.iot_short_notm}}. The device controls the content of the event and assigns a name for each event that it sends.
+Property | Data carrying part of a device event payload.
+State | The latest value of a mapped state property.
+
+
+## Information management resources
+{: #resources}
+
+You can manage the resources by using REST APIs. For information about the REST APIs, see the [{{site.data.keyword.iot_short_notm}} HTTP REST API](https://docs.internetofthings.ibmcloud.com/apis/swagger/v0002-beta/info-mgmt-beta.html) documentation.
+
+Type Resources                        | Description       
+------------- | ------------- | -------------  
+Event type                         | A programmatic construct that connects a physical interface to an event schema. </br>**Important:** For the beta, all inbound events to be used in a logical interface must be in JSON format.   
+Device type                         |  A programmatic construct that lets you group devices that share characteristics or behaviors. In interface mapping the device type is extended to include one physical interface for a device and one or more logical interfaces that are used to retrieve the device state. </br>For more information, see the "Identifiers and device types" section in the [Device Model](../reference/device_model.html#id_and_device_types) topic.
+Schema resources                         |  Programmatic constructs that define the data structure of the device type physical interfaces and the outgoing logical interfaces. The following [JSON Schemas ![External link icon](../../../icons/launch-glyph.svg "External link icon")](http://json-schema.org/){:new_window} are used: <ul><li>*Event schemas* define the structure of the events that are published to {{site.data.keyword.iot_short_notm}} by a device. Each event schema defines the structure of one inbound event and is associated with one event type. <li>*Logical interface schemas* define the structure of the device state that is stored on {{site.data.keyword.iot_short_notm}}</ul>.
+
+Interface resources                        | Description       
+------------- | ------------- | -------------  
+Logical interface | A programmatic construct that your applications can connect to or subscribe to to see the state of a device. The logical interface is defined by a logical interface schema that shapes the structure of the state data that is stored as the device state. The state is updated in response to inbound state events. A logical interfaces associated with a device type can have one physical interface as input.
+
+Instance resources                        | Description       
+------------- | ------------- | -------------  
+Device                         | A programmatic construct that represents an asset, system, or component that is registered with {{site.data.keyword.iot_short_notm}} and sends IoT data in the form of events.  
+
+Supporting resources                        | Description       
+------------- | ------------- | -------------  
+Physical interface                         | A programmatic construct that defines the event types and associated device properties that are associated with a single device type. The physical interface is defined by event schemas.   
+Mappings                         | A programmatic construct that defines how properties that are associated with inbound events are mapped to properties that are defined on a logical interface. </br>**Important:** At least one logical interface must be associated with a device type before any mappings can be defined.

GA_information_management/ga_im_device_twin.md

@@ -0,0 +1,37 @@
+---
+
+copyright:
+years: 2016, 2017
+lastupdated: "2017-05-15"
+
+---
+
+{:new_window: target="\_blank"}
+{:shortdesc: .shortdesc}
+{:screen: .screen}
+{:codeblock: .codeblock}
+{:pre: .pre}
+
+# Device twins
+{: #device_twins}
+
+A device twin is a digital representation in the cloud of a physical device or sensor that is connected to {{site.data.keyword.iot_full}}, regardless of whether the actual device is online or offline. A device twin is a logical model of the properties and events coming from a particular sensor/device. Once defined and instantiated, it provides a consistent means of interacting with a device in a REST-like manner. Because the models can be shared by multiple devices of different makes and models, the IoT application is now insulated from variability and change within the device ecosystem.
+{: shortdesc}
+
+Device twins provide more efficient ways to interact with large and diverse ecosystems of devices. {{site.data.keyword.iot_short_notm}} maintains a device twin for each connected physical device. Each device twin is uniquely identified by its name and contains a set of properties, which are stored in a JSON document. The properties of a device, including information about the current state of the device, can be retrieved by using a HTTP request to query the JSON document that represents the device twin, by using a user interface, or by subscribing to a topic.
+
+Device Twins can help you:
+- Provide your application developers with consistent interfaces to access event-driven device data in a REST-like manner.
+- Normalize data from devices of different makes or models that publish data in different formats.
+
+With {{site.data.keyword.iot_short_notm}} you can realize the device twin concept using:
+- Logical Interface metadata
+- Device type metadata
+- Device instance metadata
+
+# Next steps
+{: #device_twins_next_steps}
+
+- Create your own device twin in {{site.data.keyword.iot_short_notm}} by completing the steps outlined in the [High-level worklow](ga_im_workflow.html).
+
+For more detailed information about each of the steps outlined in the High-level worklow, see the example scenario that is documented in [Scenario](ga_im_index_scenario.html#scenario). For more information about the concepts and resources that can help you to create your device twin, see [Logical interfaces](ga_im_overview.html) and [Definitions and resources](ga_im_definitions).

GA_information_management/ga_im_example.md

@@ -0,0 +1,28 @@
+---
+
+copyright:
+years: 2016, 2017
+lastupdated: "2017-05-15"
+
+---
+
+{:new_window: target="\_blank"}
+{:shortdesc: .shortdesc}
+{:screen: .screen}
+{:codeblock: .codeblock}
+{:pre: .pre}
+
+# Using interfaces to map device data - example
+{: #im_example}
+
+The following interface example illustrates a possible solution to normalize readings from two temperature sensors into a consistent form that can be easily consumed by an application. One temperature sensor records temperature in degrees Fahrenheit and the other sensor records temperature in degrees Celsius.
+
+## Example: Mapping heterogeneous temperature sensors to a logical interface
+{: #device-type-example}
+In this example, we create a logical interface that provides homogeneous temperature state data in one format, no matter what the actual device event message payload format is. TemperatureSensor1 publishes a Celsius temperature reading of `{ "t" : 34.5 }` to {{site.data.keyword.iot_short_notm}}. TemperatureSensor2 publishes a Fahrenheit temperature reading of `{ "temp" : 72.55 }`. The temperature readings are published as separate events.
+
+For a detailed end-to-end scenario that describes this example, see the detailed [Scenario](../ga_im_index_scenario.html).
+
+![Mapping between temperature sensor devices and an application on {{site.data.keyword.iot_short_notm}}.](images/Information Management Device example.svg "Mapping between temperature sensor devices and an application on {{site.data.keyword.iot_short_notm}}")
+
+As part of the logical interface data flow you can perform calculations on incoming data to normalize these readings into a consistent form for processing. This means that you do not need to write your application to understand or convert different temperature scales. The application receives a single, normalized state and uses the **temperature** state property instead of the device specific **t** and **temp** properties.