README.md

   1 # UNICENS Service
   2
   3 ## Overview
   4 This service runs the "UNICENS Managament Library" which is responsible
   5 to start an INICnet network and configure well-known nodes and create
   6 audio/video routes.
   7 The respective network setup is described in on an XML file which is
   8 either automatically loaded after starting the service, or later on
   9 demand.
  10
  11 ## Verbs
  12
  13 | Name               | Description                                   | JSON Parameters                                                   |
  14 |--------------------|-----------------------------------------------|-------------------------------------------------------------------|
  15 | listconfig         | List configuration files in a given directory.| *Request:* {"cfgpath": "/path/to/directory"}                      |
  16 | initialise         | Initialize the service by loading a specific configuration. | *Request:* {"filename": "/path/to/file.xml"}        |
  17 | subscribe          | Subscribe to "node-availibility" event.       | *Request:* { }                                                    |
  18 | subscriberx        | Subscribe to "rx-message" event.              | *Request:* { }                                                    |
  19 | sendmessage        | Transmit a control message to a node.         | *Request:* {"node" : 624, "msgid" : 123, "data" : "AAA="}         |
  20 | writei2c           | Write I2C data to a node.                     | *Request:* {"node" : 624, "data" : [7,3,255]}                     |
  21
  22 Please note that it may not be required to call the "initialze" verb. The binding call automatically "initialize" when it is started.
  23 It automatically loads the configuration "data/config_multichannel_audio_kit.xml". This required that a compatible INICnet hardware is
  24 connected and the respective driver is initialized.
  25
  26 ## Events
  27 | Name               | Description                                   | JSON Parameters                                                   |
  28 |--------------------|-----------------------------------------------|-------------------------------------------------------------------|
  29 | node-availibility  | Availability of a node has changed.           | *Response:* {"node" : 624, "available" : true}                    |
  30 | rx-message         | Received a message from a node.               | *Response:* {"node" : 624, "msgid" : 123, "data" : "AAA="}        |
  31
  32
  33 ## Submodules
  34 This service depends on the UNICENS Management Library which is published on GitHub.
  35 See https://github.com/MicrochipTech/unicens for further information.
  36
  37 ## Hardware
  38 AGL images are pre-configured to run with Microchip Slim Board Family. For furter information see https://github.com/MicrochipTech/unicens ,
  39 section "Hardware".
  40
  41 # Build and Run on Standard Linux Distributions
  42
  43 ## Cloning Audio-Binding from Gerrit
  44
  45 ```
  46 git clone --recurse-submodules git clone https://gerrit.automotivelinux.org/gerrit/apps/agl-service-unicens
  47 cd  agl-service-unicens
  48 ```
  49
  50 ## Install AFB-Daemon from OBS
  51 See chapter "Host Configuration" in AGL developers documentation.
  52
  53 [Prerequisites](http://docs.automotivelinux.org/master/docs/devguides/en/dev/reference/host-configuration/docs/1_Prerequisites.html)
  54
  55 [AGL Application Framework](http://docs.automotivelinux.org/master/docs/devguides/en/dev/reference/host-configuration/docs/2_AGL_Application_Framework.html)
  56
  57 # Compile binding
  58
  59 ```
  60 source ~/.bashrc  # or any other file where your have place your compilation preferences
  61 mkdir -p build
  62 cd build
  63 cmake -DCMAKE_INSTALL_PREFIX=$INSTALL_PREFIX ..
  64 make
  65
  66 afb-daemon --workdir=.. --ldpaths=build --port=1234  --roothttp=./htdocs --token="" --verbose
  67
  68 speaker-test -twav -D hw:ep01 -c 2
  69 firefox http://localhost:1234
  70 ```
  71
  72 # Archive
  73
  74 ```
  75 VERSION=0.1
  76 GIT_TAG=master
  77 PKG_NAME=UNICENS-agent
  78 git archive --format=tar.gz --prefix=${PKG_NAME}-${VERSION}/ ${GIT_TAG} -o ${PKG_NAME}_${VERSION}.orig.tar.gz
  79 ```
  80
  81 # Local Source Debug with GDB
  82
  83 Warning: technically AGL bindings are shared libraries loaded thought 'dlopen'. GDB supports source debug of dynamically
  84 loaded libraries, but user should be warn that the actual path to sharelib symbols is directly inherited from DLOPEN.
  85 As a result if you change your directory after binder start with --workdir=xxx then GDB will not find symbols anymore
  86
  87 ```
  88 Examples:
  89
  90 # WORK when running in direct
  91 afb-daemon --workdir=.. --ldpaths=build --port=1234 --roothttp=./htdocs
  92
  93 # FAIL when using GDB with warning: Could not load shared library ....
  94 gdb -args afb-daemon --workdir=.. --ldpaths=build --port=1234 --roothttp=./htdocs
  95 ...
  96 warning: Could not load shared library symbols for ./build/ucs2-afb/afb-ucs2.so.
  97 Do you need "set solib-search-path" or "set sysroot"?
  98     ...
  99 ```
 100
 101 To debug sharelib symbol path: start your binder under GDB. Then break your session after the binder has
 102 loaded its bindings. Finally use "info sharedlibrary" and check 'SymsRead'. If equal to 'No' then either you start GDB
 103 from the wrong relative directory, either you have to use 'set solib-search-path' to force the path.
 104
 105 ```
 106 gdb -args afb-daemon --workdir=.. --ldpaths=build --port=1234 --roothttp=./htdocs
 107 run
 108     ...
 109     NOTICE: API UNICENS added
 110     NOTICE: Waiting port=1234 rootdir=.
 111     NOTICE: Browser URL= http://localhost:1234
 112 (hit Ctrl-C to break the execution)
 113 info sharedlibrary afb-*
 114 ```
 115
 116 # Running an debugging on a target
 117
 118 ```
 119 export RSYNC_TARGET=root@xx.xx.xx.xx
 120 export RSYNC_PREFIX=/opt    # WARNING: installation directory should exist
 121
 122 mkdir $RSYNC_TARGET
 123 cd    $RSYNC_TARGET
 124
 125 cmake -DRSYNC_TARGET=$RSYNC_TARGET -DRSYNC_PREFIX=$RSYNC_PREFIX ..
 126 make remote-target-populate
 127
 128     ./build/target/start-${RSYNC_TARGET}.sh
 129     firefox http://localhost:1234    # WARNING: do not forget firewall if any
 130
 131     ssh -tt ${RSYNC_TARGET} speaker-test -twav -D hw:ep01 -c 2
 132 ```
 133
 134 Note: remote-target-populate will
 135  - create a script to remotely start the binder on the target in ./build/target/start-on-target-name.sh
 136  - create a gdbinit file to transparently debug remotely in source code with gdb -x ./build/target/gdb-on-target-name.ini
 137  - to run and debug directly from your IDE just configure the run and debug properties with the corresponding filename
 138
 139 Note that Netbeans impose to set debug directory to ./build/pkgout or it won't find binding symbols for source debugging
 140
 141 # Default Volume of Slim Amplifiers
 142 The binding currently supports two use cases for amplifiers.
 143 1. Amplifiers are initialized with a default volume. The head unit uses software volume
 144    to change the volume of streaming data.
 145 2. Amplifiers are initialized muted. The head unit uses hardware volume (e.g. HAL-MOST-UNICENS)
 146    to change the volume of amplifiers remotely.
 147
 148 Use case 2 is the default use case. If you like to use this binding without hardware volume support
 149 please adopt the ```config_multichannel_audio_kit.xml``` as explained below.
 150
 151 ```
 152 <!-- Register 7: Master Volume (Max Volume=07 00 00 and Min Volume=07 03 FF) -->
 153 <!--   - together with HAL-MOST-UNICENS binding use "07 03 FF" = muted after start -->
 154 <!--   - otherwise use "07 01 50" = default volume -->
 155 <I2CPortWrite Address="0x2A" Payload="07 03 FF"/>
 156 ```