Merge pull request #29 from giovannicuriel/tutorial

Adding tutorials

source/components-and-apis.rst

@@ -1,3 +1,5 @@
+.. _Components and APIs:
+
 Components and APIs
 ===================
 

source/concepts.rst

@@ -0,0 +1,134 @@
+.. _Concepts:
+
+Concepts
+========
+
+This document provides information about dojot's concepts and abstractions.
+
+.. contents:: Table of Contents
+  :local:
+
+
+.. note::
+
+   - Audience
+      - Users that want to take a look at how dojot works;
+      - Application developers.
+   - Level: basic
+
+
+dojot basics
+------------
+
+Before using dojot, you should be familiar with some basic operations and
+concepts. They are very simple to understand and use, but without them, all
+operations might become obscure and senseless.
+
+In the next section, there is an explanation of a few basic entities in dojot:
+devices, templates and flows. With these concepts in mind, we present a small
+tutorial to how to use them in dojot - it only covers API access. There a GUI
+oriented tutorial in :doc:`tutorials/using-web-interface` tutorial.
+
+
+If you want more information on how dojot works internally, you should checkout
+the :doc:`architecture` to get acquainted with all internal components.
+
+.. _User authentication:
+
+User authentication
+*******************
+
+All HTTP requests supported by dojot are sent to the API gateway. In order to
+control which user should access which endpoints and resources, dojot makes
+uses of `JSON Web Token`_ (a useful tool is `jwt.io`_) which encodes things
+like (not limited to these):
+
+- User identity
+- Validation data
+- Token expiration date
+
+The component responsible for user authentication is `auth`_. You can find a
+tutorial of how to authenticate a user and how to get an access token in `auth
+documentation`_.
+
+
+Devices and templates
+*********************
+
+In dojot, a device is a digital representation of an actual device or gateway
+with one or more sensors or of a virtual one with sensors/attributes inferred
+from other devices. Throughout the documentation, this kind of device will be
+called simply as 'device'. If the actual device must be referenced, we'll be
+calling it as 'physical device'.
+
+Consider, for instance, a physical device with temperature and humidity
+sensors; it can be represented in dojot as a device with two attributes (one
+for each sensor). We call this kind of device as regular device or by its
+communication protocol, for instance, MQTT device or CoAP device.
+
+We can also create devices which don’t directly correspond to their physical
+counterparts, for instance, we can create one with higher level of information
+of temperature (is becoming hotter or is becoming colder) whose values are
+inferred from temperature sensors of other devices. This kind of device is
+called virtual device.
+
+All devices are created based on a *template*, which can be thought as a model
+of a device. As "model" we could think of part numbers or product models - one
+*prototype* from which devices are created. Templates in dojot have one label
+(any alphanumeric sequence), a list of attributes which will hold all the
+device emitted information, and optionally a few special attributes which will
+indicate how the device communicates, including transmission methods (protocol,
+ports, etc.) and message formats.
+
+In fact, templates can represent not only "device models", but it can also
+abstract a "class of devices". For instance, we could have one template to
+represent all thermometers that will be used in dojot. This template would have
+only one attribute called, let's say, "temperature". While creating the device,
+the user would select its "physical template", let's say *TexasInstr882*, and
+the 'thermometer' template. The user would have also to add translation
+instructions (implemented in terms of data flows, build in flowbuilder) in
+order to map the temperature reading that will be sent from the device to a
+"temperature" attribute.
+
+In order to create a device, a user selects which templates are going to
+compose this new device. All their attributes are merged together and
+associated to it - they are tightly linked to the original template so that any
+template update will reflect all associated devices.
+
+The component responsible for managing devices (both real and virtual) and
+templates is `DeviceManager`_. `DeviceManager documentation`_ explains in more
+depth all the available operations.
+
+
+Flows
+*****
+
+A flow is a sequence of blocks that process a particular event or device
+message. It contains:
+
+- entry point: a block representing what is the trigger to start a particular
+  flow;
+- processing blocks: a set of blocks that perform operations using the event.
+  These blocks may or may not use the contents of such event to further process
+  it. The operations might be: testing content for particular values or ranges,
+  geo-positioning analysis, changing message attributes, perform operations on
+  external elements, and so on.
+- exit point: a block representing where the resulting data should be forwarded
+  to. This block might be a database, a virtual device, an external element,
+  and so on.
+
+The component responsible for dealing with such flows is `flowbroker`_.
+
+.. _YouTube channel: https://www.youtube.com/channel/UCK1iQ-d-K-O2mOLahPOoe6w
+.. _JSON Web Token: https://tools.ietf.org/html/rfc7519
+.. _jwt.io: https://jwt.io/
+.. _auth: https://github.com/dojot/auth
+.. _auth documentation: http://dojotdocs.readthedocs.io/projects/auth/
+.. _docker-compose: https://github.com/dojot/docker-compose
+.. _DeviceManager: https://github.com/dojot/device-manager
+.. _DeviceManager documentation: http://dojotdocs.readthedocs.io/projects/DeviceManager/
+.. _DeviceManager how-to: http://dojotdocs.readthedocs.io/projects/DeviceManager/en/latest/using-device-manager.html#using-devicemanager
+.. _mashup: https://github.com/dojot/mashup
+.. _mosquitto: https://projects.eclipse.org/projects/technology.mosquitto
+.. _history APIs: https://dojot.github.io/history-ws/apiary_latest.html
+.. _flowbroker: https://github.com/dojot/flowbroker

source/faq/faq.rst

@@ -463,7 +463,7 @@ You can check all available APIs in the `API Listing page <../components-and-api
 How can I use them?
 ^^^^^^^^^^^^^^^^^^^
 
-There is a very quick and useful tutorial in the `User Guide <../user_guide.html#step-by-step-device-management>`_.
+There is a very quick and useful tutorial in the :ref:`Using API interface`.
 
 I'm interested in integrating my application with dojot. How can I do it?
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

source/index.rst

@@ -14,11 +14,19 @@ and efficient infrastructure.
    :glob:
 
    architecture
-   user_guide
+   concepts
    components-and-apis
    installation-guide
    faq/faq
 
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Tutorials
+
+   tutorials/using-web-interface
+   tutorials/using-api-interface
+
 .. Indices and tables
 .. ==================
 ..

source/installation-guide.rst

@@ -118,8 +118,9 @@ Usage
 
 The web interface is available at ``http://localhost:8000``. The user is
 ``admin`` and the password is ``admin``. You also can interact with platform
-using the :doc:`REST API <../components-and-apis>`.
+using the :ref:`Components and APIs`.
 
-Read the :doc:`../user_guide` for more information about how to interact with
-the platform.
+Read the :doc:`tutorials/using-api-interface` and
+:doc:`tutorials/using-web-interface` for more information about how to
+interact with the platform.
 

source/security/mqtt-tls.rst

@@ -109,8 +109,8 @@ payload sent with this request should be a JSON containing the end entity
 password and a CSR file (certificate intention) in base64 format.
 
 Note that the URL is 'routed' by the API gateway. As in other APIs in dojot, a
-JWT is needed. You can find how to generate and how to use such token in `User
-Guide`_.
+JWT is needed. You can find how to generate and how to use such token in
+:ref:`Using API interface`.
 
 In order to create the CSR file and ask for a certificate signature, a user can
 use a helper script called 'Certificate Retriever', which is detailed in
@@ -352,4 +352,4 @@ publish) all data is discarded by Mosquitto with no warnings.
 .. _User Guide: http://dojotdocs.readthedocs.io/en/latest/user_guide.html#first-steps
 .. _MQTT Manager repository: https://github.com/dojot/mqtt-manager
 .. _Mosquitto docker image: https://hub.docker.com/r/ansi/mosquitto
-.. _Certificate Retriever GitHub repository: https://github.com/dojot/certificate-retriever
+.. _Certificate Retriever GitHub repository: https://github.com/dojot/certificate-retriever

source/tutorials/building-an-application.rst

@@ -0,0 +1,13 @@
+.. _Building an application:
+
+Building an application
+=======================
+
+This tutorial will show how to build an application, using dojot's API
+interface.
+
+
+.. note::
+   - Who is this for: developers, solution architects
+   - Level: intermediate
+   - Reading time: X m

source/tutorials/flow.rst

@@ -0,0 +1,13 @@
+.. _Flow:
+
+Using flow builder
+==================
+
+
+This tutorial will show how to properly use flow builder to process messages
+and events generated by devices.
+
+.. note::
+   - Who is this for: entry-level users
+   - Level: basic
+   - Reading time: X m

source/tutorials/integrating-physical-devices.rst

@@ -0,0 +1,31 @@
+Integrating physical devices
+============================
+
+
+.. note::
+   - Who is this for: developers
+   - Level: intermediate
+   - Reading time: X m
+
+
+If you want to integrate your device within dojot, it must be able to send
+messages to the platform. There are two ways to do that:
+
+- Use one of the available IoT agents: currently, there is support for
+  MQTT-based devices. If your project is using (or allows changing to) this
+  protocol, then it would suffice to check if the device is sending its data
+  using a simple key/value JSON. If it isn't, then you might want to use
+  iotagent-mosca (check `iotagent-mosca`_ documentation to check out how to do
+  that). If it is indeed sending key/value JSON messages, then it can send its
+  messages to dojot's broker and it will be recognized by the platform.
+
+- Create a new IoT agent to support the protocol used by the device: if your
+  device is using another protocol that is not yet supported, then it might be
+  a good idea to implement a new IoT agent. It's not that hard, but there are a
+  few details that must be taken into account. To help developers to do such
+  thing, there is the `iotagent-nodejs`_ library which deals with most
+  internal mechanisms and messages - check its documentation to know more.
+
+
+.. _iotagent-mosca: https://github.com/dojot/iotagent-mosca
+.. _iotagent-nodejs: https://github.com/dojot/iotagent-nodejs

source/tutorials/tracking-devices.rst

@@ -0,0 +1,49 @@
+Simple device tracking
+======================
+
+In this tutorial we will focus on how to track devices and how to use flows to
+perform specific actions when a device reaches a particular area. Furthermore,
+we will see a few more GUI functionalities not covered by `Using web
+interface`_.
+
+.. NOTE::
+   - Who is this for: entry-level users
+   - Level: basic
+   - Reading time: X m
+
+
+The scenario we'll build in this tutorial will be as follows: a truck is
+carrying a container from Campinas to Pouso Alegre and we want to be notified
+when it exits Campinas, when passes by Extrema and when it reaches its
+destination. The map is shown below to help you better visualize where
+everything is located.
+
+.. raw:: html
+
+    <iframe
+    src="https://www.google.com/maps/d/embed?mid=1l8wOtclvWyD0RpDezTTz-7nWNFUzAle7"
+    width="640" height="480"></iframe>
+
+So, as done before, let's create a template with all necessary parameters and a
+new device based on it.
+
+<< insert youtube video here >>
+
+Note the ``position`` attribute, which will hold the GPS position informed by
+the truck.
+
+In order to properly generate the notification, let's create a flow that sends
+a HTTP request to an external element and updates a virtual device which
+represents one package that its is carrying. Let's create the virtual device
+first.
+
+<< insert youtube video here >>
+
+Let's create the flow.
+
+<< insert youtube video here >>
+
+Note that we added ``geofence`` nodes which defines a circle that represents
+the area of interest.
+
+.. _Using web interface: ./using-web-interface.html

source/tutorials/tracking-packages.rst

@@ -0,0 +1,40 @@
+Tracking packages
+=================
+
+This tutorial will show how to develop new pluggable modules to dojot to
+perform specific tasks. These modules are:
+
+- New nodes in flow palette (stateless procedures)
+- New modules in dojot (stateful procedures)
+
+The scenario is: we have a courier delivery services company and we need to
+track individual packages. The current package tracking is based only on
+manually scanning each device's bar code at departure and arrival in
+distribution centers. What we want is a more fine-grained system that allows
+checking where a particular package is (or it should be) in the meantime.
+
+Each package is equipped with a RFID and all courier vehicules have RFID
+scanners, LTE connection and GPS.
+
+
+.. NOTE::
+   - Who is this for: developers, solution architects
+   - Level: advanced
+   - Reading time: X m
+
+
+Implementation details
+----------------------
+
+The idea behind this is: associate each package to a vehicule and, whenever an
+update from the vehicule is received, this solution also updates all associated
+packages. The association could be done by the vehicule itself - each time a
+new device is registered by its RFID scanners, it sends a message to dojot
+indicating that the device is now associated to it. This message would be
+processed by a new software component (to be developed in this tutorial) that
+performs this association, as currently there is no module responsible for
+"device associations". When a vehicule sends a new location, this update is
+also processed by the association module, which in turn will update the
+location from all associated packages.
+
+