Commit b517051c authored by Marco Gonzalez Hierro's avatar Marco Gonzalez Hierro

Merge tag 'v1.0.1' of https://github.com/edgexfoundry/edgex-go into konnekt

v1.0.1
parents dd6a9066 c28b77d1
......@@ -153,6 +153,6 @@ docker_sys_mgmt_agent:
docker build \
-f cmd/sys-mgmt-agent/Dockerfile \
--label "git_sha=$(GIT_SHA)" \
-t edgexfoundry/sys-mgmt-agent-go:$(GIT_SHA) \
-t edgexfoundry/sys-mgmt-agent-go:$(DOCKER_TAG) \
-t edgexfoundry/docker-sys-mgmt-agent-go:$(GIT_SHA) \
-t edgexfoundry/docker-sys-mgmt-agent-go:$(DOCKER_TAG) \
.
FROM ubuntu:16.04
MAINTAINER Steve Osselton <steve@iotechsys.com>
# Install software to build docs
RUN apt-get update
RUN apt-get install -y git python-pip latexmk texlive-latex-recommended \
texlive-latex-extra texlive-fonts-recommended nodejs npm make linkchecker
RUN ln -s /usr/bin/nodejs /usr/bin/node
RUN pip install sphinx==1.7.9 sphinxcontrib-googleanalytics==0.1
RUN npm i -g raml2html@3.0.1
RUN mkdir docbuild
WORKDIR /docbuild
# Clone documentation sources in other repositories
#RUN git clone https://github.com/edgexfoundry/support-notifications
RUN git clone https://github.com/edgexfoundry/support-rulesengine
RUN git clone https://github.com/edgexfoundry/device-virtual
# Copy in local documentation sources
COPY export/* ./
COPY export/client/* ./
COPY export/distro/* ./
COPY configuration ./
COPY api ./
COPY core/* ./
COPY core/data/* ./
COPY core/metadata/* ./
COPY core/command/* ./
COPY device/* ./
COPY device/sdk/* ./
COPY device/profile/* ./
COPY device/virtual/* ./
COPY support/* ./
COPY support/scheduler/* ./
COPY support/logging/* ./
COPY support/notifications/* ./
COPY support/rulesengine/* ./
COPY system-management/* ./
COPY examples ./
COPY general ./
COPY getting-started ./
COPY walk-through ./
COPY quick-start ./
COPY security/* ./
COPY application/* ./
COPY entrypoint.sh /entrypoint.sh
ENTRYPOINT ["/entrypoint.sh"]
theme: jekyll-theme-slate
\ No newline at end of file
###################################
APIs - Core Services - Core Command
###################################
======================
Architecture Reference
======================
For a description of the architecture, see :doc:`../Ch-Command`
============
Introduction
============
EdgeX Foundry's Command microservice is a conduit for other services to trigger action on devices and sensors through their managing Device Services. The service provides an API to get the list of commands that can be issued for all devices or a single device. Commands are divided into two groups for each device:
* GET commands are issued to a device or sensor to get a current value for a particular attribute on the device, such as the current temperature provided by a thermostat sensor, or the on/off status of a light.
* PUT commands are issued to a device or sensor to change the current state or status of a device or one of its attributes, such as setting the speed in RPMs of a motor, or setting the brightness of a dimmer light.
https://github.com/edgexfoundry/edgex-go/blob/master/api/raml/core-command.raml
.. _`Core Command API HTML Documentation`: core-command.html
..
`Core Command API HTML Documentation`_
################################
APIs - Core Services - Core Data
################################
======================
Architecture Reference
======================
For a description of the architecture, see :doc:`../Ch-CoreData`
============
Introduction
============
EdgeX Foundry Core Data Service includes the device and sensor collected data database and APIs to expose the database to other services as well as north-bound integration. The database is secure. Direct access to the database is restricted to the Core Data service APIs. Core Data also provides the REST API to create and register a new device.
.. _`Core Data API HTML Documentation`: core-data.html
..
https://github.com/edgexfoundry/edgex-go/blob/master/api/raml/core-data.raml
`Core Data API HTML Documentation`_
####################################
APIs - Core Services - Core Metadata
####################################
======================
Architecture Reference
======================
For a description of the architecture, see :doc:`../Ch-Metadata`
============
Introduction
============
The Metadata microservice includes the device/sensor metadata database and APIs to expose the database to other services. In particular, the device provisioning service deposits and manages device metadata through this service. This service may also hold and manage other configuration metadata used by other services on the gateway such as clean up schedules, hardware configuration (Wi-Fi connection info, MQTT queues, and so forth). Non-device metadata may need to be held in a different database and/or managed by another service–depending upon implementation.
https://github.com/edgexfoundry/edgex-go/blob/master/api/raml/core-metadata.raml
.. _`Core Metadata API HTML Documentation`: core-metadata.html
..
`Core Metadata API HTML Documentation`_
#################################################
APIs - Core Services - Configuration and Registry
#################################################
======================
Architecture Reference
======================
For a description of the architecture, see see :doc:`../Ch-Configuration`
============
Introduction
============
The RESTful APIs are provided by Consul directly, and several communities supply Consul client libraries for different programming languages, including Go (official), Python, Java, PHP, Scala, Erlang/OTP, Ruby, Node.js, and C#.
For the client libraries of different languages, please refer to the list of this page:
https://www.consul.io/downloads_tools.html
========================
Configuration Management
========================
For the current API documentation, please refer to the official Consul web site:
https://www.consul.io/intro/getting-started/kv.html
https://www.consul.io/docs/agent/http/kv.html
================
Service Registry
================
For the current API documentation, please refer to the official Consul web site:
https://www.consul.io/intro/getting-started/services.html
https://www.consul.io/docs/agent/http/catalog.html
https://www.consul.io/docs/agent/http/agent.html
https://www.consul.io/docs/agent/checks.html
https://www.consul.io/docs/agent/http/health.html
**Service Registration**
While each microservice is starting up, it should connect to Consul to register its endpoint information, including microservice ID, address, port number, and health checking method. After that, other microservices can locate its URL from Consul, and Consul has the ability to monitor its health status. The RESTful API of registration is described on the following Consul page:
https://www.consul.io/docs/agent/http/agent.html#agent_service_register
**Service Deregistration**
Before microservices shut down, they have to deregister themsleves from Consul. The RESTful API of deregistration is described on the following Consul page:
https://www.consul.io/docs/agent/http/agent.html#agent_service_deregister
**Service Discovery**
Service Discovery feature allows client micro services to query the endpoint information of a particular microservice by its microservice IDor list all available services registered in Consul. The RESTful API of querying service by microservice IDis described on the following Consul page:
https://www.consul.io/docs/agent/http/catalog.html#catalog_service
The RESTful API of listing all available services is described on the following Consul page:
https://www.consul.io/docs/agent/http/agent.html#agent_services
**Health Checking**
Health checking is a critical feature that prevents using services that are unhealthy. Consul provides a variety of methods to check the health of services, including Script + Interval, HTTP + Interval, TCP + Interval, Time to Live (TTL), and Docker + Interval. The detailed introduction and examples of each checking methods are described on the following Consul page:
https://www.consul.io/docs/agent/checks.html
The health checks should be established during service registration. Please see the paragraph on this page of Service Registration section.
###############################################
APIs - Device Services - Virtual Device Service
###############################################
======================
Architecture Reference
======================
For a description of the architecture, see :doc:`../Ch-VirtualDevice`
=============
SDK Reference
=============
To use the Software Development Kit (SDK), see :doc:`../Ch-GettingStarted`
============
Introduction
============
The Virtual Device Service simulates different kinds of devices to generate Events and Readings to Core Data Microservice and Users can send commands and get responses through the Command and Control Microservice. The ability to do these activities is very useful when executing functional or performance tests without any real devices. This version of Virtual Device Service is implemented based on the Device Service SDK.
https://github.com/edgexfoundry/device-virtual/blob/master/raml/device-virtual.raml
.. _`Virtual Device API HTML Documentation`: device-virtual.html
..
`Virtual Device API HTML Documentation`_
This diff is collapsed.
############################################
APIs - Export Services - Client Registration
############################################
======================
Architecture Reference
======================
For a description of the architecture, see :doc:`../Ch-ClientRegistration`
============
Introduction
============
EdgeX Foundry Export Client Registration microservice enables clients to register for data from EdgeX Foundry through REST, and specify compression, encryption, format (JSON, XML), and destination of data.
https://github.com/edgexfoundry/edgex-go/blob/master/api/raml/export-client.raml
.. _`Export client API HTML Documentation`: export-client.html
..
`Export client API HTML Documentation`_
========
Examples
========
.. toctree::
:maxdepth: 2
Ch-APIExportClientRegistration-MQTT
Ch-APIExportServicesClientRegistrationExamples
#############
API Reference
#############
.. toctree::
:maxdepth: 2
Ch-APICoreServiceConfiguration
Ch-APICoreData
Ch-APICoreMetadata
Ch-APICoreCommand
Ch-APISupportingServicesAlerts
Ch-APISupportingServicesLogging
Ch-APISupportingServicesScheduling
Ch-APISupportingServicesRulesEngine
Ch-APIExportServicesClientRegistration
Ch-APIDeviceServicesVirtual
Ch-APISystemManagement
###################################################
APIs - Supporting Services - Alerts & Notifications
###################################################
======================
Architecture Reference
======================
For a description of the architecture, see :doc:`../Ch-AlertsNotifications`
============
Introduction
============
When a person or a system needs to be informed of something discovered on the node by another microservice on the node, EdgeX Foundry's Alerts and Notifications microservice delivers that information. Examples of Alerts and Notifications that other services might need to broadcast include sensor data detected outside of certain parameters, usually detected by a Rules Engine service, or a system or service malfunction, usually detected by system management services.
https://github.com/edgexfoundry/support-notifications/blob/master/raml/support-notifications.raml
.. _`Alerts and Notifications API HTML Documentation`: support-notifications.html
..
`Alerts and Notifications API HTML Documentation`_
####################################
APIs - Supporting Services - Logging
####################################
======================
Architecture Reference
======================
For a description of the architecture, see :doc:`../Ch-Logging`
============
Introduction
============
Logging Service is a microservice featuring REST API for other microservices to add, query, and delete logging requests. Two options of persistence--file or mongodb--are supported and configurable through the property file or remote consul configuration service.
https://github.com/edgexfoundry/edgex-go/blob/master/api/raml/support-logging.raml
.. _`Logging API HTML Documentation`: support-logging.html
..
`Logging API HTML Documentation`_
#########################################
APIs - Supporting Services - Rules Engine
#########################################
======================
Architecture Reference
======================
For a description of the architecture, see :doc:`../Ch-RulesEngine`
============
Introduction
============
EdgeX Foundry Rules Engine Microservice receives data from the Export Service through 0MQ, and then triggers actuation based on event data it receives and analyzes. Built on Drools technology.
https://github.com/edgexfoundry/support-rulesengine/blob/master/raml/support-rulesengine.raml
.. _`Rules engine API HTML Documentation`: support-rulesengine.html
..
`Rules engine API HTML Documentation`_
#######################################
APIs - Supporting Services - Scheduling
#######################################
======================
Architecture Reference
======================
For a description of the architecture, see :doc:`../Ch-Scheduling`
============
Introduction
============
The following API RESTful Web Services for EdgeX Foundry at this time shows the older development name of "fuse." The EdgeX Foundry name in the software will be updated soon to "edgexfoundry."
https://github.com/edgexfoundry/edgex-go/blob/master/api/raml/support-scheduling.raml
.. _`Scheduling API HTML Documentation`: support-scheduler.html
..
`Scheduling API HTML Documentation`_
===========
Description
===========
**Scheduler Service** - a service that can be used to schedule invocation of a URL. Requires the use of addressables, schedules, and schedule events.
**Addressables**
identify the called service
**Schedules**
name - unique name of the service.
start - identifies when the operation starts. Expressed in ISO 8601 YYYYMMDD'T'HHmmss format. Empty means now.
end - identifies when the operation ends. Expressed in ISO 8601 YYYYMMDD'T'HHmmss format. Empty means never
frequency - identifies the interval between invocations. Expressed in ISO 8601 PxYxMxDTxHxMxS format. Empty means no frequency.
**Schedule Events** name - unique name of the event. addressable - address information of the service to invoke parameters - any parameters that should be provided to the call, e.g. {"milliseconds":86400000} service - identifies the service that should execute the event, e.g. fuse-support-scheduler * schedule - associates the event to a schedule
========
Examples
========
Create an Addressable for the service requiring invocation
::
curl -X POST -H "Content-Type: application/json" -H "Cache-Control: no-cache" -d '{
"origin":1234567890,
"name":"pushed events",
"protocol":"HTTP",
"address":"localhost",
"port":48080,
"path":"/api/v1/event/scrub",
"publisher":null,
"user":null,
"password":null,
"topic":null }' "http://localhost:48081/api/v1/addressable"
::
curl -X POST -H "Content-Type: application/json" -H "Cache-Control: no-cache" -d '{
"origin":1234567890,
"name":"aged events",
"protocol":"HTTP",
"address":"localhost",
"port":48080,
"path":"/api/v1/event/removeold/age/604800000",
"publisher":null,
"user":null,
"password":null,
"topic":null }' "http://localhost:48081/api/v1/addressable"
Create a schedule upon which the scheduler will operate
::
curl -X POST -H "Content-Type: application/json" -H "Cache-Control: no-cache" -d '{
"origin":1234567890,
"name":"midnight",
"start":"20000101T000000",
"end":"",
"frequency":"P1D"}' "http://localhost:48081/api/v1/schedule"
Create an event that will use the schedule and invoke the addressable (drive the scrubber)
::
curl -X POST -H "Content-Type: application/json" -H "Cache-Control: no-cache" -d '{
"origin":1234567890,
"name":"pushed events",
"addressable": { "name" : "pushed events" },
"parameters": null,
"service" : "fuse-support-scheduler",
"schedule":"midnight"}' "http://localhost:48081/api/v1/scheduleevent"
::
curl -X POST -H "Content-Type: application/json" -H "Cache-Control: no-cache" -d '{
"origin":1234567890,
"name":"aged events",
"addressable": { "name" : "aged events" },
"parameters": null,
"service" : "fuse-support-scheduler",
"schedule":"midnight"}' "http://localhost:48081/api/v1/scheduleevent"
For testing update the midnight service to be every 60 seconds
::
curl -X PUT -H "Content-Type: application/json" -H "Cache-Control: no-cache" -d '{
"name":"midnight",
"frequency":"PT60S"}' "http://localhost:48081/api/v1/schedule"
################################
APIs - System Management - Agent
################################
======================
Architecture Reference
======================
Coming Soon
============
Introduction
============
The EdgeX System Management Agent (SMA) exposes the EdgeX management service API to 3rd party systems. In other words, the Agent serves as a proxy for system management service API calls into each micro service. In the future, the SMA may also offer the management API in other remote management/control system protocols like LWM2M, OMA DM, etc.
https://github.com/edgexfoundry/edgex-go/blob/master/api/raml/system-agent.raml
.. _`System Management API HTML Documentation`: system-agent.html
..
`System Management API HTML Documentation`_