connectors/iot/src/main/java/org/apache/edgent/connectors/iot/package-info.java

/*
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements.  See the NOTICE file
distributed with this work for additional information
regarding copyright ownership.  The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License.  You may obtain a copy of the License at

  http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied.  See the License for the
specific language governing permissions and limitations
under the License.
*/

/**
 * Edgent IoT device and IoT Gateway device connector API to an IoT message hub.
 * <P>
 * An IoT environment consists of an enterprise IoT message hub and devices and other clients
 * connected to it.
 * Each IoT device has an identity in the hub. The form of a device's identity is the domain
 * of an IoT hub implementation.
 * How a device becomes registered to an IoT hub and generally what device management capabilities
 * exist and how a device is managed is beyond the scope of the 
 * "analytic pipelines" focused Edgent APIs.
 * </P>
 * <P>
 * An IoT device can publish device events to and receive device commands from an IoT hub.
 * An IoT gateway device is an IoT device that is also conduit for a collection of IoT devices 
 * that lack direct connection to the enterprise IoT hub.
 * A gateway can publish events on behalf of its connected devices and 
 * receive commands from the hub targeted to them.
 * An Edgent IoT hub connector bridges the gap between this generic model and and
 * particular IoT hub implementation's underlying protocols.
 * </P>
 * <P>
 * More specifically, the generic IoT device model consists of:
 * <UL>
 * <LI>
 * <B>Device events</B> - A device {@link org.apache.edgent.connectors.iot.IotDevice#events(org.apache.edgent.topology.TStream, String, int) publishes} <em>events</em> as messages to a message hub to allow
 * analysis or processing by back-end systems, etc.. A device event consists of:
 * <UL>
 * <LI>  <B>event identifier</B> - Application specified event type. E.g. {@code engineAlert}</LI>
 * <LI>  <B>event payload</B> - Application specified event payload. E.g. the engine alert code and sensor reading.</LI>
 * <LI>  <B>QoS</B> - {@link org.apache.edgent.connectors.iot.QoS Quality of service} for message delivery. Using MQTT QoS definitions.</LI>
 * </UL>
 * Device events can be used to send any data including abnormal events
 * (e.g. a fault condition on an engine), periodic or aggregate sensor readings,
 * device user input etc.
 * <BR>
 * The format for the payload is JSON, support for other payload formats may be added
 * in the future.
 * </LI>
 * <LI>
 * <B>Device Commands</B> - A device {@link org.apache.edgent.connectors.iot.IotDevice#commands(String...) subscribes} to <em>commands</em> from back-end systems
 * through the message hub. A device command consists of:
 * <UL>
 * <LI>  <B>command identifier</B> - Application specified command type. E.g. {@code statusMessage}</LI>
 * <LI>  <B>command payload</B> - Application specified command payload. E.g. the severity and
 * text of the message to display.</LI>
 * </UL>
 * Device commands can be used to perform any action on the device including displaying information,
 * controlling the device (e.g. reduce maximum engine revolutions), controlling the Edgent application, etc.
 * <BR>
 * The format for the payload is typically JSON, though other formats may be used.
 * </LI>
 * </UL>
 * <P>
 * Device event and command identifiers starting with "{@link org.apache.edgent.connectors.iot.IotDevice#RESERVED_ID_PREFIX edgent}"
 * are reserved for use by Edgent.
 * </P>
 */
package org.apache.edgent.connectors.iot;