Merge pull request #81 from chalmers-revere/pre-release

Pre release

ChangeLog

@@ -1,3 +1,4 @@
+0.8.3 - Propagating updated OpenDaVINCI 4.5.1
 0.8.2 - Propagating update from OD4 to OpenDLV.core
 0.8.1 - New recording use cases
 0.8.0 - Supporting new messages from CAN dbc file

VERSION

@@ -1 +1 @@
-0.8.2
+0.8.3

code/core/system/health/man/opendlv-core-system-health.1

@@ -1,7 +1,7 @@
 .\" Manpage for opendlv-core-system-health
 .\" Author: Christian Berger <[email protected]>.
 
-.TH opendlv-core-system-health 1 "29 December 2016" "0.8.2" "opendlv-core-system-health man page"
+.TH opendlv-core-system-health 1 "03 January 2017" "0.8.3" "opendlv-core-system-health man page"
 
 .SH NAME
 opendlv-core-system-health \- This component checks the health of the runtime environment.

code/core/system/proxy-applanix/man/opendlv-core-system-proxy-applanix.1

@@ -1,7 +1,7 @@
 .\" Manpage for opendlv-core-proxy-applanix
 .\" Author: Christian Berger <[email protected]>.
 
-.TH opendlv-core-proxy-applanix 1 "29 December 2016" "0.8.2" "opendlv-core-proxy-applanix man page"
+.TH opendlv-core-proxy-applanix 1 "03 January 2017" "0.8.3" "opendlv-core-proxy-applanix man page"
 
 .SH NAME
 opendlv-core-proxy-applanix \- This tool interfaces to GPS/IMU unit Applanix.

code/core/system/proxy-camera-axis/man/opendlv-core-system-proxy-camera-axis.1

@@ -1,7 +1,7 @@
 .\" Manpage for opendlv-core-proxy-camera-axis
 .\" Author: Christian Berger <[email protected]>.
 
-.TH opendlv-core-proxy-camera-axis 1 "29 December 2016" "0.8.2" "opendlv-core-proxy-camera-axis man page"
+.TH opendlv-core-proxy-camera-axis 1 "03 January 2017" "0.8.3" "opendlv-core-proxy-camera-axis man page"
 
 .SH NAME
 opendlv-core-proxy-camera-axis \- This tool interfaces with Axis cameras.

code/core/system/proxy-camera/man/opendlv-core-system-proxy-camera.1

@@ -1,7 +1,7 @@
 .\" Manpage for opendlv-core-proxy-camera
 .\" Author: Christian Berger <[email protected]>.
 
-.TH opendlv-core-proxy-camera 1 "29 December 2016" "0.8.2" "opendlv-core-proxy-camera man page"
+.TH opendlv-core-proxy-camera 1 "03 January 2017" "0.8.3" "opendlv-core-proxy-camera man page"
 
 .SH NAME
 opendlv-core-proxy-camera \- This tool interfaces with the FH16 truck.

code/core/system/proxy-fh16/man/opendlv-core-system-proxy-fh16.1

@@ -1,7 +1,7 @@
 .\" Manpage for opendlv-core-proxy-fh16truck
 .\" Author: Christian Berger <[email protected]>.
 
-.TH opendlv-core-proxy-fh16truck 1 "29 December 2016" "0.8.2" "opendlv-core-proxy-fh16truck man page"
+.TH opendlv-core-proxy-fh16truck 1 "03 January 2017" "0.8.3" "opendlv-core-proxy-fh16truck man page"
 
 .SH NAME
 opendlv-core-proxy-fh16truck \- This tool interfaces with the FH16 truck.

code/core/system/proxy-imu/man/opendlv-core-system-proxy-imu.1

@@ -1,7 +1,7 @@
 .\" Manpage for opendlv-core-proxy-imu
 .\" Author: Christian Berger <[email protected]>.
 
-.TH opendlv-core-proxy-imu 1 "29 December 2016" "0.8.2" "opendlv-core-proxy-imu man page"
+.TH opendlv-core-proxy-imu 1 "03 January 2017" "0.8.3" "opendlv-core-proxy-imu man page"
 
 .SH NAME
 opendlv-core-proxy-imu \- This tool interfaces with a imu.

code/core/system/proxy-ledstrip/man/opendlv-core-system-proxy-ledstrip.1

@@ -1,7 +1,7 @@
 .\" Manpage for opendlv-core-proxy-ledstrip
 .\" Author: Christian Berger <[email protected]>.
 
-.TH opendlv-core-proxy-ledstrip 1 "29 December 2016" "0.8.2" "opendlv-core-proxy-ledstrip man page"
+.TH opendlv-core-proxy-ledstrip 1 "03 January 2017" "0.8.3" "opendlv-core-proxy-ledstrip man page"
 
 .SH NAME
 opendlv-core-proxy-ledstrip \- This tool interfaces with an LED strip.

code/core/system/proxy-sick/man/opendlv-core-system-proxy-sick.1

@@ -1,7 +1,7 @@
 .\" Manpage for opendlv-core-proxy-sick
 .\" Author: Christian Berger <[email protected]>.
 
-.TH opendlv-core-proxy-sick 1 "29 December 2016" "0.8.2" "opendlv-core-proxy-sick man page"
+.TH opendlv-core-proxy-sick 1 "03 January 2017" "0.8.3" "opendlv-core-proxy-sick man page"
 
 .SH NAME
 opendlv-core-proxy-sick \- This tool interfaces with the Sick lidar device.

code/core/system/proxy-trimble/man/opendlv-core-system-proxy-trimble.1

@@ -1,7 +1,7 @@
 .\" Manpage for opendlv-core-proxy-trimble
 .\" Author: Christian Berger <[email protected]>.
 
-.TH opendlv-core-proxy-trimble 1 "29 December 2016" "0.8.2" "opendlv-core-proxy-trimble man page"
+.TH opendlv-core-proxy-trimble 1 "03 January 2017" "0.8.3" "opendlv-core-proxy-trimble man page"
 
 .SH NAME
 opendlv-core-proxy-trimble \- This tool interfaces to GPS/IMU unit Trimble.

code/core/system/proxy-v2v/man/opendlv-core-system-proxy-v2v.1

@@ -1,7 +1,7 @@
 .\" Manpage for opendlv-core-proxy-v2v
 .\" Author: Christian Berger <[email protected]>.
 
-.TH opendlv-core-proxy-v2v 1 "29 December 2016" "0.8.2" "opendlv-core-proxy-v2v man page"
+.TH opendlv-core-proxy-v2v 1 "03 January 2017" "0.8.3" "opendlv-core-proxy-v2v man page"
 
 .SH NAME
 opendlv-core-proxy-v2v \- This tool interfaces with a V2V unit.

code/core/system/proxy-velodyne16/man/opendlv-core-system-proxy-velodyne16.1

@@ -1,7 +1,7 @@
 .\" Manpage for opendlv-core-proxy-velodyne16
 .\" Author: Christian Berger <[email protected]>.
 
-.TH opendlv-core-proxy-velodyne16 1 "29 December 2016" "0.8.2" "opendlv-core-proxy-velodyne man page"
+.TH opendlv-core-proxy-velodyne16 1 "03 January 2017" "0.8.3" "opendlv-core-proxy-velodyne man page"
 
 .SH NAME
 opendlv-core-proxy-velodyne16 \- This tool interfaces with the FH16 truck.

code/core/system/proxy-velodyne64/man/opendlv-core-system-proxy-velodyne64.1

@@ -1,7 +1,7 @@
 .\" Manpage for opendlv-core-proxy-velodyne
 .\" Author: Christian Berger <[email protected]>.
 
-.TH opendlv-core-proxy-velodyne 1 "29 December 2016" "0.8.2" "opendlv-core-proxy-velodyne man page"
+.TH opendlv-core-proxy-velodyne 1 "03 January 2017" "0.8.3" "opendlv-core-proxy-velodyne man page"
 
 .SH NAME
 opendlv-core-proxy-velodyne \- This tool interfaces with the FH16 truck.

code/core/system/ps3controller/man/opendlv-core-system-ps3controller.1

@@ -1,7 +1,7 @@
 .\" Manpage for opendlv-core-ps3controller
 .\" Author: Christian Berger <[email protected]>.
 
-.TH opendlv-core-ps3controller 1 "29 December 2016" "0.8.2" "opendlv-core-ps3controller man page"
+.TH opendlv-core-ps3controller 1 "03 January 2017" "0.8.3" "opendlv-core-ps3controller man page"
 
 .SH NAME
 opendlv-core-ps3controller \- This tool interfaces with the FH16 truck.

docker/Makefile

@@ -18,7 +18,7 @@
 ###############################################################################
 # Parameters for this Makefile.
 BASE_IMAGE=seresearch/opendavinci-ubuntu-16.04-complete
-BASE_IMAGE_VERSION=v4.5.0
+BASE_IMAGE_VERSION=v4.5.1
 
 ###############################################################################
 # Tools.

usecases/stable/demo-ps3controller/README.md

@@ -0,0 +1,79 @@
+# Controlling the FH16 Truck Using the PS3 Controller
+
+This folder provides instructions on how to use the PS3 controller to control the FH16 truck. The demo is supposed to run on the truck PC. Before continuing with the instructions below, SSH to this computer.
+
+## Check & Set Up Periphery
+
+Before starting the usecase, make sure all periphery is working and sending data.
+
+### PS3 Controller
+
+#### Test
+
+After connecting the controller, a device node will be created in `/dev/input`. To see which controller device nodes are available, run
+
+    $ ls /dev/input/js*
+
+After plugging in, the four LEDs left to the USB connector of the controller should be flashing. Press the round button in the center of the controller, labelled with the PlayStation logo, to turn on the controller. If the LEDs stop flashing at some point, the controller stopped working. Replug it and start again.
+
+To check whether the controller is actually sending data, run
+
+    $ cat /dev/input/js0
+
+assuming that `js0` is the name of the device node corresponding to the controller. If this is the right node and the controller is working, there should be console output when you move the joysticks and press buttons. If you have more than one `js*` device node, check until you find the one which produces output.
+
+#### Set Up
+
+Check whether the device name matches the mapping in `docker-compose.yml`.  If the device name determined in the previous step does not match the **left** side of the mapping, change it accordingly.
+
+Example: Suppose your PS3 controller is attached to `/dev/input/js1`, while in docker-compose the mapping says:
+
+    devices:
+        - /dev/input/js0:/dev/input/js0
+        
+In that case, change the left side of the mapping to `/dev/input/js0`:
+
+    devices:
+        - /dev/input/js1:/dev/input/js0
+        
+The right side of the mapping shall not be changed and should correspond to the `system-ps3controller.ps3controllerdevicenode` value in `configuration`.
+
+### CAN Interface
+
+#### Test
+
+Connect the truck's CAN cable to the interface on the car PC. Make sure the truck sends CAN data, e.g. by turning on the engine. Check whether you get CAN data by running
+
+    $ cat /dev/pcanpci2
+
+There should be lots of output. If there is not, try with a different interface number (`ls /dev/pcanpci*` for the possible numbers).
+
+#### Set Up
+
+Check whether the device name matches the mapping in `docker-compose.yml`.  If the device name determined in the previous step does not match the **left** side of the mapping, change it accordingly.
+
+Example: Suppose you get CAN data on `/dev/pcanpci0`, while in docker-compose the mapping says:
+
+    devices:
+        - /dev/pcanpci2:/dev/pcan2
+        
+In that case, change the left side of the mapping to `/dev/pcanpci0`:
+
+    devices:
+        - /dev/pcanpci0:/dev/pcan2
+        
+The right side of the mapping shall not be changed and should correspond to the `proxy-fh16.devicenode` value in `configuration`.
+
+## Start the Usecase
+
+To build the usecases' image and run the usecase, run:
+
+    $ docker-compose up --build
+
+To exit the containers of the usecase, hit `Ctrl+C`. Afterwards, to stop them, run:
+
+    $ docker-compose stop
+
+To actually remove the containers of the usecase, run
+
+    $ docker-compose rm

usecases/stable/documentationcamera/calibrate.documentationcamera.realtime/README.md

@@ -1,38 +1,55 @@
-This folder provides the instructions for viewing runtime video feed with a single OpenCV camera. This use case is particularly used for adjusting the mounting position and angle of a documentation camera in the car. A docker-compose file is provided to start all micro-services to display runtime video feed. It includes three services: odsupercomponent, health, and opendlv-core-system-proxy-camera (or proxy-camera for short). odsupercomponent is used for software component lifecycle management in OpenDaVINCI. health checks the status of device nodes. proxy-camera activates the camera and enables a pop-up video display window. It is assumed that git, Docker, and Docker Compose are installed and the camera is properly connected. To install Docker, follow the tutorial: https://docs.docker.com/engine/installation/linux/ubuntulinux/.
+# Displaying the Live Image of a Camera
+
+This folder provides the instructions for viewing the live image video of a V4L camera with real-time scheduling. This can be used for adjusting the mounting of a camera in the car and needs to be run on a system with a screen. The following micro-services are included: odsupercomponent, health, proxy-camera. odsupercomponent is used for software component lifecycle management in OpenDaVINCI. health checks the status of device nodes. proxy-camera activates the camera and displays a pop-up window with the live image.
 
-### Prepare proxy-camera
+## Setup Camera Device
 
-proxy-camera is included in the opendlv.core repository (https://github.com/chalmers-revere/opendlv.core). Clone the opendlv.core source:
+Camera devices are listed in `/dev`. To check whether the camera is successfully attached, do
 
-    $ git clone https://github.com/chalmers-revere/opendlv.core
-
-    $ git pull
+    $ ls /dev/video*
 
-Go to opendlv.core/docker, build and create the Docker image seresearch/opendlv-core-on-opendavinci-ubuntu-16.04-complete:latest:
+which should give you the list of attached cameras. If the attached camera is not `/dev/video0`, modify the left side of the device mapping of `proxy-camera` in `docker-compose.yml`. For example if your camera device is `/dev/video2`, change the mapping from 
 
-    $ make buildComplete
-
-    $ make createDockerImage
+    devices:
+        - /dev/video0:/dev/video0
+        
+to
+
+    devices:
+        - /dev/video2:/dev/video0
+        
+The right side of the mapping shall not be changed.
 
-### Use proxy-camera with Docker Compose
+## Start the usecase
 
-Go to the folder usecases/calibrate.documentationcamera. This folder contains a checkHealth.sh script, a configuration file, a docker-compose file docker-compose.yml, and an environment file .env. The environment file .env defines an environment variable CID which is referred to by the docker-compose file. CID is a user-defined environment variable that specifies the cid of the UDP session established by odsupercomponent. In .env CID has the value 201, thus in docker-compose.yml "${CID}" resolves to 201.  Run Docker Compose:
+To start the usecase, run
 
     $ docker-compose up --build
 
-Then proxy-camera will start a pop-up window that displays live video feed from the camera. To stop the camera display (e.g., when the camera mounting position calibration is completed), run
+This should open a new window that displays the live video image from the camera. To stop, hit `Ctrl+C` in the terminal window. To leave the system in a clean state, stop all the containers of the usecase and remove them:
 
-    $ docker-compose stop
-
-Then remove all stopped containers:
+    $ docker-compose stop && docker-compose rm
 
-    $ docker-compose rm
+## Troubleshooting
 
-Note that the value of CID defined in .env can be manually overwritten by preceding the docker-compose command with CID=xxx, where xxx is the cid number. For instance, the following command makes odsupercomponent, proxy-camera, and odrecorderh264 run with cid 123 instead of 201:
+### Real-time kernel
 
-    $ CID=123 docker-compose up
-    
-Then CID=123 should also be used for docker-compose stop and docker-compose rm accordingly.
+This use case assumes that the Linux operating system has a real-time kernel which should enable a smoother video compared with a non-real-time kernel. To display the kernal information, run
+
+    $ uname -a
 
-Finally, note that this use case assumes that the camera is mounted upside down. Hence video images are flipped for that reason. The configuration file in this folder includes a parameter proxy-camera.camera.flipped which is set to 1. In order to disable flipped images, change its value to 0.
+### Flipped Camera Image
 
+It is assumed that the camera is mounted upside down, thus the video images are flipped before displaying. To disable flipping, set `proxy-camera.camera.flipped` in `configuration` to `0`.
+
+### odsupercomponent
+
+If the `odsupercomponent` service fails to start, try altering the `CID` in the file `.env`.
+
+### Camera Image
+
+If there are problems, try
+
+    $ ffplay -i /dev/video0
+
+where `/dev/video0` is the video device you want to test. This will also open a window with the live image of the camera and might help precluding potential error sources.

usecases/stable/documentationcamera/calibrate.documentationcamera.realtime/docker-compose.yml

@@ -25,6 +25,24 @@ services:
         volumes:
             - .:/opt/opendlv.core.configuration
         command: "/opt/od4/bin/odsupercomponent --cid=${CID} --verbose=1 --configuration=/opt/opendlv.core.configuration/configuration"
+
+    # Micro-service for health.
+    # The host's /dev and /proc directories are mapped into the Docker container
+    # to check for expected properties like device nodes. The privileged flag
+    # allows the unrestricted access.
+    health:
+        build: .
+        depends_on:
+            - odsupercomponent
+        network_mode: host
+        restart: always
+        privileged: true
+        volumes:
+            - .:/opt/opendlv.core.configuration
+            - /dev:/from.host/dev
+            - /proc:/from.host/proc
+        working_dir: "/opt/opendlv.core.configuration"
+        command: "/opt/opendlv.core/bin/opendlv-core-system-health --cid=${CID} --freq=1"
 
     # Micro-service for proxy-camera.
     proxy-camera:

usecases/stable/documentationcamera/calibrate.documentationcamera/README.md

@@ -1,38 +1,49 @@
-This folder provides the instructions for viewing runtime video feed with a single OpenCV camera. This use case is particularly used for adjusting the mounting position and angle of a documentation camera in the car. A docker-compose file is provided to start all micro-services to display runtime video feed. It includes three services: odsupercomponent, health, and opendlv-core-system-proxy-camera (or proxy-camera for short). odsupercomponent is used for software component lifecycle management in OpenDaVINCI. health checks the status of device nodes. proxy-camera activates the camera and enables a pop-up video display window. It is assumed that git, Docker, and Docker Compose are installed and the camera is properly connected. To install Docker, follow the tutorial: https://docs.docker.com/engine/installation/linux/ubuntulinux/.
+# Displaying the Live Image of a Camera
+
+This folder provides the instructions for viewing the live image video of a V4L camera. This can be used for adjusting the mounting of a camera in the car and needs to be run on a system with a screen. The following micro-services are included: odsupercomponent, health, proxy-camera. odsupercomponent is used for software component lifecycle management in OpenDaVINCI. health checks the status of device nodes. proxy-camera activates the camera and displays a pop-up window with the live image.
 
-### Prepare proxy-camera
+## Setup Camera Device
 
-proxy-camera is included in the opendlv.core repository (https://github.com/chalmers-revere/opendlv.core). Clone the opendlv.core source:
+Camera devices are listed in `/dev`. To check whether the camera is successfully attached, do
 
-    $ git clone https://github.com/chalmers-revere/opendlv.core
-
-    $ git pull
+    $ ls /dev/video*
 
-Go to opendlv.core/docker, build and create the Docker image seresearch/opendlv-core-on-opendavinci-ubuntu-16.04-complete:latest:
+which should give you the list of attached cameras. If the attached camera is not `/dev/video0`, modify the left side of the device mapping of `proxy-camera` in `docker-compose.yml`. For example if your camera device is `/dev/video2`, change the mapping from 
 
-    $ make buildComplete
-
-    $ make createDockerImage
+    devices:
+        - /dev/video0:/dev/video0
+        
+to
+
+    devices:
+        - /dev/video2:/dev/video0
+        
+The right side of the mapping shall not be changed.
 
-### Use proxy-camera with Docker Compose
+## Start the usecase
 
-Go to the folder usecases/calibrate.documentationcamera. This folder contains a checkHealth.sh script, a configuration file, a docker-compose file docker-compose.yml, and an environment file .env. The environment file .env defines an environment variable CID which is referred to by the docker-compose file. CID is a user-defined environment variable that specifies the cid of the UDP session established by odsupercomponent. In .env CID has the value 201, thus in docker-compose.yml "${CID}" resolves to 201.  Run Docker Compose:
+To start the usecase, run
 
     $ docker-compose up --build
 
-Then proxy-camera will start a pop-up window that displays live video feed from the camera. To stop the camera display (e.g., when the camera mounting position calibration is completed), run
+This should open a new window that displays the live video image from the camera. To stop, hit `Ctrl+C` in the terminal window. To leave the system in a clean state, stop all the containers of the usecase and remove them:
 
-    $ docker-compose stop
-
-Then remove all stopped containers:
+    $ docker-compose stop && docker-compose rm
 
-    $ docker-compose rm
+## Troubleshooting
 
-Note that the value of CID defined in .env can be manually overwritten by preceding the docker-compose command with CID=xxx, where xxx is the cid number. For instance, the following command makes odsupercomponent, proxy-camera, and odrecorderh264 run with cid 123 instead of 201:
+### Flipped Camera Image
 
-    $ CID=123 docker-compose up
-
-Then CID=123 should also be used for docker-compose stop and docker-compose rm accordingly.
+It is assumed that the camera is mounted upside down, thus the video images are flipped before displaying. To disable flipping, set `proxy-camera.camera.flipped` in `configuration` to `0`.
+
+### odsupercomponent
+
+If the `odsupercomponent` service fails to start, try altering the `CID` in the file `.env`.
 
-Finally, note that this use case assumes that the camera is mounted upside down. Hence video images are flipped for that reason. The configuration file in this folder includes a parameter proxy-camera.camera.flipped which is set to 1. In order to disable flipped images, change its value to 0.
+### Camera Image
 
+If there are problems, try
+
+    $ ffplay -i /dev/video0
+
+where `/dev/video0` is the video device you want to test. This will also open a window with the live image of the camera and might help precluding potential error sources.