agl-service-unicens: refresh readme file

Bug-AGL: SPEC-2105

- add general description
- add API verbs and events
- refresh paths to git repositories
- cleanup markdown formatting for headers

Change-Id: I0f561ad31ba675c1db8ab09267959e9a97968fa8
Signed-off-by: Tobias Jahnke <tobias.jahnke@microchip.com>

1 files changed, 71 insertions, 86 deletions

diff --git a/README.md b/README.md
index cf9a380..b47f201 100644
--- a/README.md
+++ b/README.md
@@ -1,87 +1,72 @@
-------------------------------------------------------------------------
-AGL-UNICENS binding expose UNICENS-V2 APIs through AGL framework
-------------------------------------------------------------------------
+# UNICENS Service
 
-Cloning Audio-Binding from Git
--------------------------------------------------------
+## Overview
+This service runs the "UNICENS Managament Library" which is responsible
+to start an INICnet network and configure well-known nodes and create
+audio/video routes.
+The respective network setup is described in on an XML file which is
+either automatically loaded after starting the service, or later on
+demand.
 
-```
-git clone --recurse-submodules https://github.com/iotbzh/unicens2-binding
-cd  unicens2-binding
-```
+## Verbs
+
+| Name               | Description                                   | JSON Parameters                                                   |
+|--------------------|-----------------------------------------------|-------------------------------------------------------------------|
+| listconfig         | List configuration files in a given directory.| *Request:* {"cfgpath": "/path/to/directory"}                      |
+| initialise         | Initialize the service by loading a specific configuration. | *Request:* {"filename": "/path/to/file.xml"}        |
+| subscribe          | Subscribe to "node-availibility" event.       | *Request:* { }                                                    |
+| subscriberx        | Subscribe to "rx-message" event.              | *Request:* { }                                                    |
+| sendmessage        | Transmit a control message to a node.         | *Request:* {"node" : 624, "msgid" : 123, "data" : "AAA="}         |
+| writei2c           | Write I2C data to a node.                     | *Request:* {"node" : 624, "data" : [7,3,255]}                     |
+
+Please note that it may not be required to call the "initialze" verb. The binding call automatically "initialize" when it is started.
+It automatically loads the configuration "data/config_multichannel_audio_kit.xml". This required that a compatible INICnet hardware is
+connected and the respective driver is initialized.
+
+## Events
+| Name               | Description                                   | JSON Parameters                                                   |
+|--------------------|-----------------------------------------------|-------------------------------------------------------------------|
+| node-availibility  | Availability of a node has changed.           | *Response:* {"node" : 624, "available" : true}                    |
+| rx-message         | Received a message from a node.               | *Response:* {"node" : 624, "msgid" : 123, "data" : "AAA="}        |
 
-AFB_daemon dependency on Standard Linux Distributions
--------------------------------------------------------
-    # handle dependencies > (OpenSuse-42.2, Fedora-25, Ubuntu 16.04.2LTS)
-    gcc > 4.8
-    systemd-devel (libsystemd-dev>=222)
-    libuuid-devel
-    file-devel(OpenSuSe) or libmagic-dev(Ubuntu)
-    libjson-c-devel
-    alsa-devel
-    ElectricFence (BUG should not be mandatory)
-    libopenssl-devel libgcrypt-devel libgnutls-devel (optional but requested by libmicrohttpd for https)
-    libxml2-devel
 
-    OpenSuse >=42.2
-      zypper in gcc5 gdb gcc5-c++ git cmake make ElectricFence systemd-devel libopenssl-devel  libuuid-devel alsa-devel libgcrypt-devel libgnutls-devel libjson-c-devel file-devel libxml2-devel
+## Submodules
+This service depends on the UNICENS Management Library which is published on GitHub.
+See https://github.com/MicrochipTech/unicens for further information.
 
-    Ubuntu >= 16.4 libuuid-devel
-      apt-get install cmake git electric-fence libsystemd-dev libssl-dev uuid-dev libasound2-dev libgcrypt20-dev libgnutls-dev libgnutls-dev libjson-c-dev libmagic-dev libxml2-dev
+## Hardware
+AGL images are pre-configured to run with Microchip Slim Board Family. For furter information see https://github.com/MicrochipTech/unicens ,
+section "Hardware".
 
-    libmicrohttpd>=0.9.55 (as today OpenSuse-42.2 or Ubuntu-.16.4 ship older versions)
-    afb-daemon from AGL Gerrit git clone https://gerrit.automotivelinux.org/gerrit/src/app-framework-binder
+# Build and Run on Standard Linux Distributions
+
+## Cloning Audio-Binding from Gerrit
 
 ```
-    # Might want to add following variables into ~/.bashrc
-    echo "#----------  AGL options Start ---------" >>~/.bashrc
-    echo "# Object: AGL cmake option for  binder/bindings" >>~/.bashrc
-    echo "# Date: `date`" >>~/.bashrc
-    echo 'export CC=gcc-5; export CXX=g++-5' >>~/.bashrc   # if using gcc5
-    echo 'export INSTALL_PREFIX=$HOME/opt' >>~/.bashrc
-    echo 'export LD_LIBRARY_PATH=$INSTALL_PREFIX/lib64:$INSTALL_PREFIX/lib' >>~/.bashrc
-    echo 'export LIBRARY_PATH=$INSTALL_PREFIX/lib64:$INSTALL_PREFIX/lib' >>~/.bashrc
-    echo 'export PKG_CONFIG_PATH=$INSTALL_PREFIX/lib64/pkgconfig:$INSTALL_PREFIX/lib/pkgconfig' >>~/.bashrc
-    echo 'export PATH=$INSTALL_PREFIX/bin:$PATH' >>~/.bashrc
-    echo 'export RSYNC_TARGET=MY_TARGET_HOSTNAME' >>~/.bashrc
-    echo 'export RSYNC_PREFIX=./opt' >>~/.bashrc
-
-    echo "#----------  AGL options End ---------" >>~/.bashrc
-    source ~/.bashrc
-
-    # install LibMicroHttpd
-    LIB_MH_VERSION=0.9.55
-    wget https://ftp.gnu.org/gnu/libmicrohttpd/libmicrohttpd-${LIB_MH_VERSION}.tar.gz
-    tar -xzf libmicrohttpd-${LIB_MH_VERSION}.tar.gz
-    cd libmicrohttpd-${LIB_MH_VERSION}
-    ./configure --prefix=${INSTALL_PREFIX}
-    make
-    sudo make install-strip
-
-    # retrieve last AFB_daemon from AGL
-    git clone https://gerrit.automotivelinux.org/gerrit/src/app-framework-binder
-
-    # Warning: previous GCC options should be set before initial cmake (clean Build/*)
-    cd app-framework-binder; mkdir -p build; cd build
-    cmake -DCMAKE_INSTALL_PREFIX=$INSTALL_PREFIX ..
-    make
-    make install
+git clone --recurse-submodules git clone https://gerrit.automotivelinux.org/gerrit/apps/agl-service-unicens
+cd  agl-service-unicens
 ```
 
+## Install AFB-Daemon from OBS
+See chapter "Host Configuration" in AGL developers documentation.
+
+[Prerequisites](http://docs.automotivelinux.org/master/docs/devguides/en/dev/reference/host-configuration/docs/1_Prerequisites.html)
+
+[AGL Application Framework](http://docs.automotivelinux.org/master/docs/devguides/en/dev/reference/host-configuration/docs/2_AGL_Application_Framework.html)
 
 # Compile binding
 
 ```
-    source ~/.bashrc  # or any other file where your have place your compilation preferences
-    mkdir -p build
-    cd build
-    cmake -DCMAKE_INSTALL_PREFIX=$INSTALL_PREFIX ..
-    make
+source ~/.bashrc  # or any other file where your have place your compilation preferences
+mkdir -p build
+cd build
+cmake -DCMAKE_INSTALL_PREFIX=$INSTALL_PREFIX ..
+make
 
-    afb-daemon --workdir=.. --ldpaths=build --port=1234  --roothttp=./htdocs --token="" --verbose
+afb-daemon --workdir=.. --ldpaths=build --port=1234  --roothttp=./htdocs --token="" --verbose
 
-    speaker-test -twav -D hw:ep01 -c 2
-    firefox http://localhost:1234
+speaker-test -twav -D hw:ep01 -c 2
+firefox http://localhost:1234
 ```
 
 # Archive
@@ -100,16 +85,16 @@ loaded libraries, but user should be warn that the actual path to sharelib symbo
 As a result if you change your directory after binder start with --workdir=xxx then GDB will not find symbols anymore
 
 ```
-    Examples:
+Examples:
 
-    # WORK when running in direct
-    afb-daemon --workdir=.. --ldpaths=build --port=1234 --roothttp=./htdocs
+# WORK when running in direct
+afb-daemon --workdir=.. --ldpaths=build --port=1234 --roothttp=./htdocs
 
-    # FAIL when using GDB with warning: Could not load shared library ....
-    gdb -args afb-daemon --workdir=.. --ldpaths=build --port=1234 --roothttp=./htdocs
-    ...
-    warning: Could not load shared library symbols for ./build/ucs2-afb/afb-ucs2.so.
-    Do you need "set solib-search-path" or "set sysroot"?
+# FAIL when using GDB with warning: Could not load shared library ....
+gdb -args afb-daemon --workdir=.. --ldpaths=build --port=1234 --roothttp=./htdocs
+...
+warning: Could not load shared library symbols for ./build/ucs2-afb/afb-ucs2.so.
+Do you need "set solib-search-path" or "set sysroot"?
     ...
 ```
 
@@ -118,14 +103,14 @@ loaded its bindings. Finally use "info sharedlibrary" and check 'SymsRead'. If e
 from the wrong relative directory, either you have to use 'set solib-search-path' to force the path.
 
 ```
-    gdb -args afb-daemon --workdir=.. --ldpaths=build --port=1234 --roothttp=./htdocs
-    run
-        ...
-        NOTICE: API UNICENS added
-        NOTICE: Waiting port=1234 rootdir=.
-        NOTICE: Browser URL= http://localhost:1234
-    (hit Ctrl-C to break the execution)
-    info sharedlibrary afb-*
+gdb -args afb-daemon --workdir=.. --ldpaths=build --port=1234 --roothttp=./htdocs
+run
+    ...
+    NOTICE: API UNICENS added
+    NOTICE: Waiting port=1234 rootdir=.
+    NOTICE: Browser URL= http://localhost:1234
+(hit Ctrl-C to break the execution)
+info sharedlibrary afb-*
 ```
 
 # Running an debugging on a target
@@ -153,9 +138,9 @@ Note: remote-target-populate will
 
 Note that Netbeans impose to set debug directory to ./build/pkgout or it won't find binding symbols for source debugging
 
-# Default Volume of Amplifiers
+# Default Volume of Slim Amplifiers
 The binding currently supports two use cases for amplifiers.
-1. Amplifiers are initialized with a default volume. The head unit uses software volume 
+1. Amplifiers are initialized with a default volume. The head unit uses software volume
    to change the volume of streaming data.
 2. Amplifiers are initialized muted. The head unit uses hardware volume (e.g. HAL-MOST-UNICENS)
    to change the volume of amplifiers remotely.