SAN Installation
Installing SAN on the machine connected to your sensor can be done in two ways: using the cloned GitLab repository's source code, or simply using a Docker container, which allows you to run SAN with no inconvenience of clicking through source folders and files.
Using the convenient Docker container
If you are running SAN from Docker on a Raspberry Pi or Revolution Pi, you will need to replace every occurrence of l4ms/opil.iot.san:stable
with l4ms/opil.iot.san:stableRPI
Once you have docker installed on the machine connecting your sensor, all that is necessary to get the SAN container from the cloud is to run the following command in a terminal window:
sudo docker pull l4ms/opil.iot.san:stable
This will clone the latest stable version of SAN onto your machine.
You can now move on to the getting started section.
Cloning the GitLab repository
This is not recommended for the end user as it provides no advantages over the Docker container, unless access to the source code is absolutely necessary.
Run git clone https://gitlab.com/opil_group/mod.iot.san
in a terminal window opened in the folder where you want the source code to be cloned to.
You can now move on to the getting started section.
Updating SAN
Updating the Docker container simply requires you to run the same command you used to install the SAN container:
sudo docker pull l4ms/opil.iot.san:stable
Updating the source code requires a git pull:
git pull https://gitlab.com/opil_group/mod.iot.san
Getting started: SAN Setup using Docker
If you have cloned the source repository, you do not need to create a docker-compose.yaml or Dockerfile and can move on to editing your existing config.json file in mod.iot.san/src/PythonSAN
. You will also need to replace the existing config.rsc file in mod.iot.san/src/PythonSAN/Drivers
with your own.
For Docker setup follow the instructions to create the mandatory files.
Creating the mandatory files to run SAN in a Docker container
After you have pulled the Docker image from the cloud, you should create a folder to house the necessary files to run and configure SAN.
If you are running SAN from Docker on a Raspberry Pi or Revolution Pi, you will need to replace every occurrence of l4ms/opil.iot.san:stable
with l4ms/opil.iot.san:stableRPI
If you are running SAN from Docker on a Revolution Pi, you will need to get your config.rsc file (usually from /etc/revpi/), and move it into the same folder where your config.json and Docker files are
docker-compose.yaml
The first file you should create is a docker-compose.yaml file. Open it in an editor and enter the following:
version: '3'
services:
san:
image: l4ms/opil.iot.san:stableRPI
#give root permissions and name SAN
privileged: true
container_name: 'SAN'
#show informational messages from SAN in interactive terminal
stdin_open: true
tty: true
#hijack host ip for internal server
network_mode: 'host'
#restart container in case of trouble unless stopped by user
restart: unless-stopped
#buildcontext
build:
context: ./
dockerfile: ./Dockerfile
This file will tell Docker where it should look for instructions to configure the container, and where the files needed are.
Dockerfile
Next you should create a Dockerfile. Note that this file does not have a set filetype. Open it in an editor and enter the following:
#This tells Docker what image to use as a base that it builds on
FROM l4ms/opil.iot.san:stable
#COPY statements copy files FROM somewhere on your machine TO somewhere in the
#docker container. You can add/uncomment statements to copy your drivers and config
#to the container.
#COPY FROM TO
COPY ./config.json /code
#COPY ./config.rsc /code/Drivers #uncomment this line if you are using a RevPi and need to add IO configuration
#COPY ./YOUR_DRIVER.py /code/Drivers #uncomment this line if you want to add your driver
#This part checks the slimness of the container. Do not change.
RUN apt-get update && apt-get -y upgrade
RUN apt-get -y autoremove
WORKDIR /code
#starting container from the main SAN process, so that the termination signal is sent there
ENTRYPOINT ["python3", "./san.py"]
These are the instructions to Docker on how to configure SAN.
If you are using Docker you will need to create your own config.json file in the same folder as your docker-compose.yaml and Dockerfile. After that, you should copy the following initial, demonstrative version of the file into your created file, and change the "host" field to your OCB host address.
Demonstrative generic config.json file
The example of generic JSON file for configuration looks like this:
{
"contextBroker": {
"host": "192.168.0.100",
"port": "1026"
},
"sanConfig": {
"sensors": [
{
"sensorID": "demo_sensor1",
"operationMode": {
"mode": "event-driven"
},
"driver": "DemoDriver",
"driverConfig": {
"ioPin": "18",
"sensorType": "ON_OFF_SENSOR",
"measurementType": "boolean",
"sensorManufacturer": "DemoCompany"
},
"sanID": "demo_SAN1"
}
]
}
}
For an in-depth explanation of each possible field in the config.json file, refer to the API Documentation SAN section.
Initialising SAN using cloned git repo
1) Open a Terminal. 2) Navigate to mod.iot.san/installation 3) ./sanInstall.sh 4) Restart terminal
Running SAN demo
Once you have created your config.json file or edited the pre-existing one's "host" field to your OCB address, you can now run the SAN demo, which simply sends an alternating boolean signal to the OCB server.
Running SAN demo with Docker
If you are running SAN from Docker on a Raspberry Pi or Revolution Pi, you will need to replace every occurrence of l4ms/opil.iot.san:stable
with l4ms/opil.iot.san:stableRPI
If you are running SAN from Docker on a Revolution Pi, you will need to get your config.rsc file (usually from /etc/revpi/), and move it into the same folder where your config.json and Docker files are
In order to push the new configuration file that you made to the docker container you will need to run the following command in the terminal opened in the SAN folder:
sudo docker-compose build
After that you can run the following command to start SAN in the same terminal window:
sudo docker-compose up
Running with cloned git repo
Navigate into mod.iot.san/src/PythonSAN
, and run the following command in the terminal window opened in that folder:
sudo python3 san.py
Stopping SAN
1) Find the terminal where the SAN is running. 2) Press Ctrl+C. 3) SAN will stop all running update threads and automatically clean up dangling information from the OCB server. Docker will not show SAN's successful stop message, but as long as the server was cleaned up (no more graphs on HMI), shutdown was successful.
Where to next?
In order to be able to properly interface your sensors to SAN, you will need to write SAN drivers for them. For that, refer to the SAN part of the API Documentation section.
SAN Deinstallation
This explains how to remove SAN.
Remove Docker image
If you have run SAN as a Docker image, follow these steps:
docker rm l4ms/opil.iot.san:stable
Or, to completely clean your storage from any docker images/containers:
docker system prune -a
Remove repo downloaded from GIT
Here, you will have to locate the directory mod.iot.san and remove it manually.
Updating SAN
Updating the Docker container simply requires you to run the same command you used to install the SAN container:
sudo docker pull l4ms/opil.iot.san:stable
You will have to re-apply your custom changes for every update by re-building.
Updating the source code requires a git pull:
git pull https://gitlab.com/opil_group/mod.iot.san
SAN Deprecated
Currently there are no deprecated functionalities, however, some of the deprecated components may be found in deprecated folder of the source, but they are mostly for development and debugging reasons.