Metadata-Version: 1.1
Name: vesna-alhtools
Version: 1.0.0
Summary: Tools for talking the VESNA almost-like-HTTP protocol
Home-page: https://github.com/avian2/vesna-alh-tools
Author: Tomaz Solc
Author-email: tomaz.solc@tablix.org
License: GPL
Description: .. vim:sw=3 ts=3 expandtab tw=78
        
        Introduction
        ============
        
        This package provides utilities and Python modules for managing VESNA-based
        wireless sensor networks that are using the ALH protocol.
        
        In a typical setup, VESNA nodes participate in a ZigBee-based wireless mesh
        network. On this mesh network each sensor node exposes a HTTP-like interface,
        supporting two types of requests: GET for state-less information retrieval
        and POST for state-changing actions.
        
        The ZigBee mesh is established by the coordinator. In addition to a ZigBee
        interface, the coordinator also typically has an Ethernet adapter. At boot it
        establishes a TCP/IP SSL tunnel and exposes an ALH service over it.
        
        Usually, the SSL tunnel terminates in an infrastructure server that performs
        the translation between ALH and a proper HTTP REST interface exposed on the
        web::
        
           +------+
           | node | ALH -  ZigBee mesh
           +------+      \
                         |                    SSL tunnel
           +------+      |      +-------------+         +----------------+
           | node | ALH -+- ALH | coordinator | ALH --- | infrastructure | HTTPS -->
           +------+      |      +-------------+         +----------------+
                         |
           +------+      /
           | node | ALH -
           +------+
        
        Alternatively, coordinator can also be directly connected to a client over a
        serial line. This setup is typically used for development or debugging::
        
           +------+
           | node | ALH -  ZigBee mesh
           +------+      \
                         |                      serial line
           +------+      |      +-------------+
           | node | ALH -+- ALH | coordinator | ALH ------------------------------->
           +------+      |      +-------------+
                         |
           +------+      /
           | node | ALH -
           +------+
        
        These tools transparently support both modes of operation. Typically either URL of the
        HTTP REST endpoint is given or a character device for the serial line.
        
        
        Installation
        ============
        
        To install system-wide, run::
        
           $ python setup.py install
        
        You also need to install Python bindings for VESNA spectrum sensor
        application. You can get it at:
        
        https://github.com/sensorlab/vesna-spectrum-sensor
        
        See its own README file for installation instructions.
        
        For communication over the serial line, python-serial package is needed::
        
           $ apt-get install python-serial
        
        
        Usage
        =====
        
        After installation, the following tools are available:
        
        ``alh-reprogram``
           Perform over-the-air reprogramming of the coordinator or sensor nodes.
        
        ``alh-map``
           Enumerate all the nodes participating in the sensor network by crawling the
           ZigBee mesh.
        
           Can be used for visualizing the network using Graphviz or network
           monitoring (via integration into Munin).
        
        ``alh-tx-test``
           Signal generator test.
        
        ``alh-endpoint-server``
           Simple ALH-to-HTTP endpoint server, useful for testing. It can be used
           instead of the proper infrastructure server.
        
        
        Run each with ``--help`` as the only argument to get a list of available
        options.
        
        Note: if the API end-point is using basic authentication, you will be
        prompted for credentials on the command line.
        
        You can also save credentials into either a file named ``.alhrc`` in your
        home directory or ``alhrc`` in the current directory. Format of the file is
        as in the following example::
        
           Host example.com
           User <username>
           Password <password>
           # more Host, User, Password lines can follow
        
        Several Python modules are installed as well. Refer to demo programs in the
        demos/ directory for examples on how to use them and docstring
        documentation for details.
        
        
        Remote testing with rftest.py
        =============================
        
        This library provides a DeviceUnderTest class that is compatible with the
        RF test utility from vesna-spectrum-sensor repository. It allows for testing of
        radio hardware (e.g. SNE-ISMTV) using the production firmware (e.g.
        NodeSpectrumSensor application) on a fully assembled node with minimal
        additional wiring.
        
        Testing setup looks like this::
        
           +----------+ coax +------+ zigbit +-------------+  SSL  +----------------+
           | R&S SMBV |----->| node |<-------| coordinator |<------| infrastructure |
           +----------+      +------+  ALH   +-------------+       +----------------+
                 ^                                                           ^
                 | usbtmc    +--------+  HTTPS                               |
                 +-----------| rftest |--------------------------------------+
                             +--------+
        
        Run rftest like this::
        
           $ vesna-rftest -i foo -R vesna.alh.rftest.RemoteDeviceUnderTest -O,-Uhttps://...,-u...,-n1
        
        
        License
        =======
        
        Copyright (C) 2015 SensorLab, Jozef Stefan Institute
        http://sensorlab.ijs.si
        
        This program is free software: you can redistribute it and/or modify
        it under the terms of the GNU General Public License as published by
        the Free Software Foundation, either version 3 of the License, or
        (at your option) any later version.
        
        This program is distributed in the hope that it will be useful,
        but WITHOUT ANY WARRANTY; without even the implied warranty of
        MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
        GNU General Public License for more details.
        
        You should have received a copy of the GNU General Public License
        along with this program.  If not, see <http://www.gnu.org/licenses/>.
        
        Authors:	Tomaz Solc, <tomaz.solc@ijs.si>
        
Platform: UNKNOWN
Requires: vesna
