Skip to content

GitLab

Home · Changes

Page history
Update home authored by Wouter Jansen's avatar Wouter Jansen
Hide whitespace changes
Inline Side-by-side
home.md 0 → 100644
View page @ 92da4842
# RTIS Update Usage Documentation
This web application allows you to update any existing RTIS Software packages installed as well as install new ones.
Furthermore, this application can update the firmware on a connected RTIS device.
This primary way to do so is with an internet connection that can retrieve updates from the Cosys-Lab GIT server.
However, this service can run offline and is therefore able to update RTIS devices without an active internet connection.
For this offline patch files can be uploaded to the service and installed.
## Features
* The web interface shows all currently tracked and installed software packages.
* For offline updates, new installation and updates are installed using `.rtispatch` files distributed by a Cosys-Lab member.
* Self-upgrade can make sure RTIS Update stays up to date and can do both offline and online self-updating.
* Any software package can be tracked and updated.
* Git bundles can be used to install and update existing software packages with support for Git submodules if offline.
* The STM32 firmware of an RTIS device can be found and flashed on Jetson systems both offline and online.
* Services can be automatically installed and updated. Furthermore, these can be restarted/stopped through the interface.
* Local Markdown documentation files of applications can be linked and rendered on the web interface.
* Next to Git updates the system allows Powershell and Shell scripts on Windows and Linux respectively to be used to further perform installation and update steps.
## Dependencies
Version numbers are those used during this project, higher versions likely supported too unless otherwise mentioned.
* Python 3.6 or higher with modules:
* multiprocessing-logging
* flask
* PySerial (On windows for getting RTIS Device firmware)
* RTIS Serial (On Linux for getting and installing RTIS Device firmware)
* stm32loader (For installing RTIS Device firmware on Jetson devices)
* Jetson.GPIO (For installing RTIS Device firmware on Jetson devices)
* Powershell on Windows for running scripts
* apt-offline on Linux for installing packages when no internet is available
* An internet connection and GIT credentials for online updates
## Installation
Ideally RTIS Update should be running the background at all times. Therefore, it can be installed as a service. Alternatively, you can manually start it.
### Manual
This Web service application is a Python script. It can be started from the command line using the following command:
```bash
python3 RTISUpdateWeb.py
```
It supports several launch arguments to configure this application:
- `-h`/`--help`: show a help message about the launch arguments
- `--log` : Disable or configure log files. 0=off , 1=only warnings and errors, 2(default)=includes info, 3=includes debug
- `--install_folder` : Folder where to install new RTIS Software. Default=_/home/cosyslab/rtis-software_
- `--install_user` : User with rights to execute elevated commands with. Default=_cosyslab_
- `--device_port` : The port on which to find the connected RTIS device. Default=_/dev/ttyACM0_
- `--host_ip` : The IP to host the updater web page on. default=_localhost_
- `--host_port` : The port to host the updater web page on. default=_8001_
- `--online_url` : The online URL where the online update list can be found. Default=_[https://cosysgit.uantwerpen.be/rtis-software/rtisupdate/-/snippets/28/raw/main/software_list.json](https://cosysgit.uantwerpen.be/rtis-software/rtisupdate/-/snippets/28/raw/main/software_list.json)_
- `--git_username` : The cosys-git username to use for online updates.
- `--git_password` : The cosys-git password to use for online updates.
-
for example:
```bash
python3 RTISUpdateWeb.py --host_ip 192.168.1.150 --install_folder /mnt/data/rtis-software
```
Do note that for allowing online updates that use the GIT server to retrieve them, the GIT credentials have to be provided.
### Windows service
To make RTIS Update run in the background on your system you can install it as a Windows service.
To do so, you can use the automatic installer script [`install_service.ps1`](Web/install_service.ps1) available in the *Web* folder.
This script will install the service and start it. You can optionally supply several launch arguments to the script to configure the Web service.
To learn more about these launch arguments see above in the [manual](#manual) section.
An example on how to add launch arguments:
```powershell
cd Web
.\install_service.ps1 "--install_folder C:\Users\cosyslab\rtis-software --log 3 --git_username myusername --git_password mypassword"
```
Do note that for allowing online updates that use the GIT server to retrieve them, the GIT credentials have to be provided.
### Linux service
To make RTIS Update run in the background on your system you can install it as a Systemd service on Linux.
To do so, you can use the automatic installer script [`install_service.sh`](Web/install_service.sh) available in the *Web* folder.
This script will install the service and start it. The first argument should always be the username with elevated privileges that the service should be using.
You can optionally add supply several launch arguments to the script to configure the Web service.
To learn more about these launch arguments see above in the [manual](#manual) section.
Make sure to run the script with `sudo`.
An example on how to add launch arguments:
```bash
cd Web
sudo ./install_service.sh cosyslab --install_folder /mnt/data/rtis-software --log 3 --git_username myusername --git_password mypassword
```
Do note that for allowing online updates that use the GIT server to retrieve them, the GIT credentials have to be provided.
## Interface usage
The web interface is available at the IP and port specified in the launch arguments.
The interface is divided into two sections: the top section is about uploading/installing new software packages and the bottom section shows the currently installed software packages.
To update or install a new package use the uploader to upload a `.rtispatch` file. It will then show all available packages in the patch file and allow you to install those that can be.
You also have several other functions such as service management and access to the wiki and repository links.
## Creating an offline patch
A patch is the file that a user can upload and apply using RTIS Update. RTIS Update is versatile but will depend on properly created and tested patch files to work without errors.
a patch file uses a simple `.zip` renamed as `.rtispatch` to avoid confusion. The 4 types of files that can be expected in such a compressed archive are:
- `patch_software.json`: This file contains the information about the software packages that are in the patch. It is explained in the [next section](#json-description).
- **GIT bundles**: These are files that contain a Git repository's changes between revisions. They are used to install/update software packages for GIT based applications. It is explained in the [GIT bundles section](#git-bundles).
- **script files**: These are Windows powershell scripts (`.ps1`) or Linux shell scripts (`.sh`) that can be run during installation/update to do additional steps such as dependency installations, compiling, etc. It is explained in the [script files section](#script-files).
- **Additional files**: If your scripts require additional files such as dependencies or compiled binaries, you can include them as well in the patch archive.
### Software requirements
The software you wish to install/update should:
- be either a Python module or a standalone app that can be run with a single command.
- If a standalone app have a `version.txt` which only contains the current version in _Major.Minor.Bugfix_ format.
- If a Python module have a `__version__` variable which contains the current version in _Major.Minor.Bugfix_ format.
- Should be able to be fully installed offline and without user interaction. Anything should be scriptable through Bash on Linux or Powershell on Windows.
### JSON description
A mandatory file within the patch archive is the `patch_software.json` file.
This describes the software contained within and is parsed to do the installation of the software, services and running the scripts. It has the following structure:
The
```json
{
"rtissoftware1": { [string, The name of the software package in the backend. Also used as folder name!]
"name": "RTIS Software 1", [string, The public name of the software package as should be shown to the user]
"version": "2.0.1", [string, The version of the software package in 'Major.Minor.Bugfix' format]
"repo": "https://cosysgit.uantwerpen.be/rtissoftware1", [OPTIONAL, string, The URL pointing to the repository of this software package]
"wiki": "https://cosysgit.uantwerpen.be/rtissoftware1/-/wikis/home", [OPTIONAL, string, The URL pointing to the wiki page/documentation of this software package]
"type": "standalone", [string, Intentifying the software type. Can be 'standalone', 'script' or 'pythonmodule' currently]
"doc": "README.md", [OPTIONAL if using 'standalone' type, string, The local filename containing a Markdown documentation file that can be displayed even when offline]
"scriptfile": "rtissoftware_2_0_1_script", [OPTIONAL, string, pointing to the file in the patch archive containing the script file. Should not include the '.sh' or '.ps1' extensions!]
"patchfile": "rtissoftware_2_0_1.bundle", [OPTIONAL, string, pointing to the file in the patch archive containing the main GIT bundle file]
"branch": "v2.0.1", [if using 'patchfile', string, The name of the branch of the software package to be found in the main bundle]
"submodules": { [OPTIONAL, sub-dictionary, containing the submodules of this software package]
"rtiscommon": { [string, The name of the submodule in the backend. Also used as folder name!]
"folder": "Python/External", [OPTIONAL, string, If the submodule is not in the root of the software folder, this points to the folder containing the submodule]
"patchfile": "rtiscommon_3_0_0.bundle", [string, pointing to the file in the patch archive containing the GIT bundle file for this submodule]
"branch": "v3.0.0" [string, The name of the branch of the software package to be found in the bundle of this submodule]
},
...
},
"services": { [OPTIONAL, sub-dictionary, containing the services of this software package]
"rtissoftware1service": { [string, The name of the service in the backend. Also used as service name!]
"workingdirectory": "Python", [OPTIONAL, string, the sub-folder containing the script to launch as service]
"type": "python", [string, the type of service command. if set to 'python' it automatically creates the launching of a Python script set in the 'command'. If not it just runs the 'command' as is]
"command": "RTISSoftware1.py", [string, the command to run. If 'type' is set to 'python' this should be the name of the Python script to launch]
"restart": 1, [integer, if set to 1 or higher it will be installed as an automatic-restart service. On linux the value will be used as the restart timer. If 0, it will act as a one-shot service for example used on boot-up]
"enabled": 0, [0 or 1, if set to 1 it will be enabled automatically. If set to 0 it will be disabled]
"after": "multi-user.target myotherservice.service", [some additional arguments can be given for Linux services (with supported parameter names)]
"environment": "LD_LIBRARY_PATH=/usr/lib/rtiscuda",
"wants": "network-online.target",
"wanted": "network-online.target",
...
},
...
}
},
"rtissoftware2": {
...
}
```
### GIT bundles
To install new software or update exising ones, RTIS Update uses GIT bundles. One needs to make a bundle for each repository and indicate which tag/branch/revision to use for it.
Each submodule also requires its own bundle.
To make a bundle for a repository with a specific branch/tag, you can use the following command from the repository/submodule folder:
```bash
```bash
git bundle create rtissoftware_2_0_1.bundle v2.0.1
```
### Script files
Optionally additional scripts can be included in the patch archive. These scripts can be used to do additional steps such as installing dependencies, compiling, etc.
On Windows Powershell scripts are used whereas on Linux shell scripts must be placed within the patch archive. The output of the scripts is displayed to the user.
Specific lines can be added to the script to provide feedback to the user.
Scripts will always be run from the folder where the patch files are extracted to, which is the [Patches](Patches) folder.
By default, the `install_folder` and `install_user` (see more details in the [manual installation section](#manual)) parameters are provided as arguments to all scripts in that order.
#### Windows Powershell scripts
To indicate completion a progress bar is displayed in the user's browser. To set this progress bar, the following line can be added to the script:
```powershell
echo "UPDATE_PROGRESS_X"
```
with _X_ marking the percentage value of the progress bar. For example: `echo "UPDATE_PROGRESS_15"`
To show a specific message to the user some commands are also available. The following lines can be added to the script:
```powershell
echo "UPDATE_MESSAGE_your message"
echo "UPDATE_WARNING_your warning"
echo "UPDATE_ERROR_your error"
```
This will show the message in either green, yellow or red respectively based on if you use a normal, warning or error message.
An example script using this is for example:
```powershell
echo "UPDATE_MESSAGE_Starting the script!"
echo "UPDATE_PROGRESS_15"
echo "UPDATE_MESSAGE_This is my message"
echo "UPDATE_WARNING_This is my warning"
echo "UPDATE_ERROR_This is my error"
echo "UPDATE_PROGRESS_50"
echo "UPDATE_MESSAGE_Executing the ipconfig command..."
ipconfig
echo "UPDATE_MESSAGE_Execution done!"
echo "UPDATE_PROGRESS_100"
```
Another example is how to get the current Python version:
```powershell
$pythonversion = & py -V 2>&1
$supportedpython = 0
if($pythonversion -like '*3.6*'){
echo "UPDATE_MESSAGE_Using Python 3.6"
$supportedpython = 1
}else{
echo "UPDATE_ERROR_Wrong Python version detected."
}
```
To see if a Python module is installed you can use some code like this example:
```powershell
if(py -m pip show rtisdev){
echo "UPDATE_MESSAGE_RTIS Dev module found!"
}else{
echo "UPDATE_ERROR_RTIS Dev module not found, install it!"
}
```
#### Linux Shell scripts
With linux scripts, don't forget to add `#!/usr/bin/env bash` at the top of the script file!
To indicate completion a progress bar is displayed in the user's browser. To set this progress bar, the following line can be added to the script:
```bash
echo "UPDATE_PROGRESS_X"
```
with _X_ marking the percentage value of the progress bar. For example: `echo "UPDATE_PROGRESS_15"`
To show a specific message to the user some commands are also available. The following lines can be added to the script:
```bash
echo "UPDATE_MESSAGE_your message"
echo "UPDATE_WARNING_your warning"
echo "UPDATE_ERROR_your error"
```
This will show the message in either green, yellow or red respectively based on if you use a normal, warning or error message.
An example script using this is for example:
```bash
#!/usr/bin/env bash
echo "UPDATE_MESSAGE_Starting the script!"
echo "UPDATE_PROGRESS_15"
echo "UPDATE_MESSAGE_This is my message"
echo "UPDATE_WARNING_This is my warning"
echo "UPDATE_ERROR_This is my error"
echo "UPDATE_PROGRESS_50"
echo "UPDATE_MESSAGE_Executing the ipconfig command..."
ifconfig
echo "UPDATE_MESSAGE_Execution done!"
echo "UPDATE_PROGRESS_100"
```
Another example is how to get the current Python version:
```bash
PY_VER_MAJOR="0"
PY_VER_MINOR="0"
if which python3 > /dev/null 2>&1;
then
PY_VER_MAJOR="$(python3 -c 'import sys; print(sys.version_info[0])')"
PY_VER_MINOR="$(python3 -c 'import sys; print(sys.version_info[1])')"
fi
if [ "${PY_VER_MAJOR}" = "3" ];
then
if [ "${PY_VER_MINOR}" == "6" ];
then
echo "UPDATE_MESSAGE_Python v3.6 detected."
else
echo "UPDATE_ERROR_Python installation found but is not version 3.6. Please install python 3.6."
exit 1
fi
else
echo "UPDATE_ERROR_Python installation not found with command 'python3'. Please install python 3.6."
exit 1
fi
```
To see if a Python module is installed you can use some code like this example:
```bash
if python3 -c "import rtisdev" > /dev/null 2>&1 -eq 0;
then
echo "UPDATE_MESSAGE_RTIS Dev module found!"
else
echo "UPDATE_ERROR_RTIS Dev module not found, install it!"
fi
```
#### Offline pip installations
To get offline pip installations working, the following steps are required:
- Create a `requirements.txt` file that holds all the packages to be installed. For example:
```text
PyQt5
pyqtgraph
matplotlib
```
- Use the `pip download` command to download all these packages to a folder for a specific python version. For example:
```bash
python3 -m pip download -r requirements.txt --only-binary=:all: --python-version=3.6
```
You can download these for multiple Python versions as well.
- Once you have all the packages downloaded, place them in your patch archive together with the `requirements.txt` file . Then add a `pip install` command within your script:
```bash
python3 -m pip install -r requirements.txt --no-index --find-links .
```
This will automatically search for the packages needed for the python version that is being used.
#### Offline aptitude installations on Linux
To get offline aptitude(`apt-get install...`) installations working, the following steps are required:
- The offline system requires to have `apt-offline` installed.
- Make sure you are running on a **VERY** similar system with online access. Run the `apt-offline set `command as for example:
```bash
apt-offline set --install-packages YOUR_PROGRAM --update apt-offline.sig
```
- Use the `apt-offline get` command to generate an archive holding all the packages and its dependencies. For example:
```bash
apt-offline get --bundle YOUR_PROGRAM.zip apt-offline.sig
```
- Once you have the archive, place it in your patch archive. Then add a `apt-offline install` command within your script:
```bash
apt-offline install YOUR_PROGRAM.zip --skip-changelog
```
This will automatically install/update your program and its dependencies.
#### Offline aptitude installations on Linux
To get offline aptitude(`apt-get install...`) installations working, the following steps are required:
- The offline system requires to have `apt-offline` installed.
- Make sure you are running on a **VERY** similar system with online access. Run the `apt-offline set `command as for example:
```bash
apt-offline set --install-packages YOUR_PROGRAM --update apt-offline.sig
```
- Use the `apt-offline get` command to generate an archive holding all the packages and its dependencies. For example:
```bash
apt-offline get --bundle YOUR_PROGRAM.zip apt-offline.sig
```
- Once you have the archive, place it in your patch archive. Then add a `apt-offline install` command within your script:
```bash
apt-offline install YOUR_PROGRAM.zip --skip-changelog
```
This will automatically install/update your program and its dependencies.
### Firmware installation
Currently only supported on Jetson devices, the RTIS device firmware can also be updated using _stm32loader_ and _Jetson.GPIO_. This requires some particular attributes in the `patch_software.json` file.
The update name and attribute `type` should always be set to `firmware`.
Furthermore, the binary firmware file should also be present in the patch archive as well as defined in the JSON description under the `filename` attribute.
Finally, you can optionally add the `port` attribute to override the automatic detection of the right port as well as customize the stm32 switch-pin with the `stm32pin` attribute (default=7).
An example JSON description:
```json
{
"firmware": {
"name": "RTIS Device Firmware",
"version": "1.5.0",
"type": "firmware",
"filename": "v1.5.0.bin",
"port": "/dev/ttyTHS2",
"stm32pin": 9
}
}
```
### Self-upgrade
RTIS update can also update itself. This works rather similarly to other patches but requires some particular things to work correctly.
The update name should always be `rtisupdate` as this is in the backend hardcoded to be the name of the RTIS Update self-upgrade package.
Furthermore, the version is similarly checked to be higher based on what is listed in the `patch_software.json` file.
A example JSON description:
```json
{
"rtisupdate": {
"name": "RTIS Update",
"version": "5.0.0",
"repo": "https://cosysgit.uantwerpen.be/rtis-software/rtisupdate",
"wiki": "https://cosysgit.uantwerpen.be/rtis-software/rtisupdate/-/wikis/home",
"doc": "README.md",
"type": "standalone",
"patchfile": "rtisupdate_5_0_0.bundle",
"scriptfile": "rtisupdate_5_0_0",
"branch": "v5.0.0"
}
}
```
It should also include a script to install/restart the service that runs RTIS Update in the background.
This script is always launched with arguments that will contain the same launch arguments as the currently running script.
For example on Windows and Linux respectively you can use:
```powershell
echo "RTIS Update offline installation script for Windows Systems - v5.0.0"
if(get-service rtisupdate){
echo " RTIS Update Service..."
Restart-Service -Name rtisupdate -Force
echo "RTIS Update Service restarted!"
}else
{
echo "Installing RTIS Update Service..."
$pythonpath = (python -c "import os, sys; print(os.path.dirname(sys.executable))") + "\python.exe"
$updatepath = (pwd).path
$updatescript = $updatepath + "\RTISUpdateWeb.py " + $args[0]
.\nssm.exe install rtisupdate $pythonpath $updatescript ; .\nssm.exe set rtisupdate AppDirectory $updatepath
echo "RTIS Update Service installed!"
echo "Starting RTIS Update Service..."
Restart-Service -Name rtisupdate -Force
echo "RTIS Update Service started!"
}
echo "Installation completed!"
```
```bash
#!/usr/bin/env bash
echo "RTIS Update offline installation script for Linux Systems - v5.0.0"
if systemctl cat rtisupdate;
then
echo " RTIS Update Service..."
service rtisupdate restart
echo "RTIS Update Service restarted!"
else
argumentsgiven="${@:2}"
echo $'[Unit]\nDescription=RTIS Update Service\nAfter=multi-user.target\n\n[Service]' >> /etc/systemd/system/rtisupdate.service
echo "ExecStart=/usr/bin/python3 ${PWD%/*}/RTISUpdateWeb.py ${argumentsgiven}" >> /etc/systemd/system/rtisupdate.service
echo "WorkingDirectory=${PWD%/*}" >> /etc/systemd/system/rtisupdate.service
echo "User=${1}" >> /etc/systemd/system/rtisupdate.service
echo $'Restart=always\nRestartSec=3\n\n[Install]\nWantedBy=multi-user.target' >> /etc/systemd/system/rtisupdate.service
chmod 644 /etc/systemd/system/rtisupdate.service
systemctl daemon-reload
echo "RTIS Update Service installed!"
echo "Starting RTIS Update Service..."
service rtisupdate restart
echo "RTIS Update Service started!"
fi
echo "Installation completed!"
```
## Creating an online update
Similarly, as offline updates, online updates can be performed using the RTIS Update web interface once an internet connection is available.
This does require the correct configuration of the launch arguments `.online_url`, `.git_username` and `.git_userpassword`. To learn more about these launch arguments see above in the [manual](#manual) section.
By default, all online updates are kept as [snippets](https://cosysgit.uantwerpen.be/rtis-software/rtisupdate/-/snippets) in the RTIS Update repository.
### Software requirements
The software you wish to install/update should:
- be either a Python module or a standalone app that can be run with a single command.
- If a standalone app have a `version.txt` which only contains the current version in _Major.Minor.Bugfix_ format.
- If a Python module have a `__version__` variable which contains the current version in _Major.Minor.Bugfix_ format.
- Should be able to be fully installed offline and without user interaction. Anything should be scriptable through Bash on Linux or Powershell on Windows.
### Online JSON descriptions
All available updates should be kept online in a downloadable JSON. By default, this is saved in [this snippet](https://cosysgit.uantwerpen.be/rtis-software/rtisupdate/-/snippets/28).
The description of updates is similar to offline patches. They describe the software contained available to be downloaded and is parsed to do the installation of the software, services and running the scripts. It has the following structure:
```json
{
"rtissoftware1": { [string, The name of the software package in the backend. Also used as folder name!]
"name": "RTIS Software 1", [string, The public name of the software package as should be shown to the user]
"version": "2.0.1", [string, The version of the software package in 'Major.Minor.Bugfix' format]
"type": "standalone", [string, Intentifying the software type. Can be 'standalone', 'script' or 'pythonmodule' currently]
"doc": "README.md", [OPTIONAL if using 'standalone' type, string, The local filename containing a Markdown documentation file that can be displayed even when offline]
"installation_script": "https://.../-/snippets/50/raw/main", [string, pointing to the prefix URL which holds the 'installation.sh' and 'installation.ps1' files.]
"git_required": 1, [integer, Indicates if the script requires Cosys-Lab Gitlab server credentials.]
"repo": "https://cosysgit.uantwerpen.be/rtissoftware1", [OPTIONAL, string, The URL pointing to the repository of this software package]
"wiki": "https://cosysgit.uantwerpen.be/rtissoftware1/-/wikis/home", [OPTIONAL, string, The URL pointing to the wiki page/documentation of this software package]
"services": { [OPTIONAL, sub-dictionary, containing the services of this software package]
"rtissoftware1service": { [string, The name of the service in the backend. Also used as service name!]
"workingdirectory": "Python", [OPTIONAL, string, the sub-folder containing the script to launch as service]
"type": "python", [string, the type of service command. if set to 'python' it automatically creates the launching of a Python script set in the 'command'. If not it just runs the 'command' as is]
"command": "RTISSoftware1.py", [string, the command to run. If 'type' is set to 'python' this should be the name of the Python script to launch]
"restart": 1, [integer, if set to 1 or higher it will be installed as an automatic-restart service. On linux the value will be used as the restart timer. If 0, it will act as a one-shot service for example used on boot-up]
"enabled": 0, [0 or 1, if set to 1 it will be enabled automatically. If set to 0 it will be disabled]
"after": "multi-user.target myotherservice.service", [some additional arguments can be given for Linux services (with supported parameter names)]
"environment": "LD_LIBRARY_PATH=/usr/lib/rtiscuda",
"wants": "network-online.target",
"wanted": "network-online.target",
...
},
...
}
},
"rtissoftware2": {
...
}
```
### Update script files
To install new software or update exising ones online, RTIS Update uses scripts.
On Windows Powershell scripts are used whereas on Linux shell scripts must be placed within the patch archive.
The online JSON description file explained above will link to the prefix URL which holds the `installation.sh` and `installation.ps1` files.
For example, if the `installation_script` is "https://cosysgit.uantwerpen.be/rtis-software/rtisupdate/-/snippets/31/raw/main" then the system will expect the `installation.sh` and `installation.ps1` files under URLs:
- https://cosysgit.uantwerpen.be/rtis-software/rtisupdate/-/snippets/31/raw/main/installation.sh
- https://cosysgit.uantwerpen.be/rtis-software/rtisupdate/-/snippets/31/raw/main/installation.ps1
respectively. The output of the scripts is displayed to the user.
Specific lines can be added to the script to provide feedback to the user.
By default, the `install_folder` and `install_user` (see more details in the [manual installation section](#manual)) parameters are provided as arguments to all scripts in that order.
If set, the `git_username` and `git_password` will also be provided to these scripts. This is needed to pull repositories from the Cosys-Lab Gitlab server.
If they are provided the order of arguments given to the scripts is `install_folder`, `git_username`, `git_password`, `install_user`.
#### Windows Powershell scripts
To indicate completion a progress bar is displayed in the user's browser. To set this progress bar, the following line can be added to the script:
```powershell
echo "UPDATE_PROGRESS_X"
```
with _X_ marking the percentage value of the progress bar. For example: `echo "UPDATE_PROGRESS_15"`
To show a specific message to the user some commands are also available. The following lines can be added to the script:
```powershell
echo "UPDATE_MESSAGE_your message"
echo "UPDATE_WARNING_your warning"
echo "UPDATE_ERROR_your error"
```
This will show the message in either green, yellow or red respectively based on if you use a normal, warning or error message.
An example script using this is for example:
```powershell
echo "UPDATE_MESSAGE_Starting the online installation script!"
echo "UPDATE_PROGRESS_15"
py -m pip install mypythondependency
$install_folder = $args[0]
$gitusername = $args[1]
$gitpassword = $args[2]
cd $install_folder
$reponame = "https://" + $gitusername + ":" + $gitpassword + "@cosysgit.uantwerpen.be/rtis-software/rtissoftware.git"
git clone $reponame
echo "UPDATE_MESSAGE_This is my message"
echo "UPDATE_WARNING_This is my warning"
echo "UPDATE_ERROR_This is my error"
echo "UPDATE_PROGRESS_50"
echo "UPDATE_MESSAGE_Execution done!"
echo "UPDATE_PROGRESS_100"
```
Another example is how to get the current Python version:
```powershell
$pythonversion = & py -V 2>&1
$supportedpython = 0
if($pythonversion -like '*3.6*'){
echo "UPDATE_MESSAGE_Using Python 3.6"
$supportedpython = 1
}else{
echo "UPDATE_ERROR_Wrong Python version detected."
}
```
To see if a Python module is installed you can use some code like this example:
```powershell
if(py -m pip show rtisdev){
echo "UPDATE_MESSAGE_RTIS Dev module found!"
}else{
echo "UPDATE_ERROR_RTIS Dev module not found, install it!"
}
```
#### Linux Shell scripts
With linux scripts, don't forget to add `#!/usr/bin/env bash` at the top of the script file!
To indicate completion a progress bar is displayed in the user's browser. To set this progress bar, the following line can be added to the script:
```bash
echo "UPDATE_PROGRESS_X"
```
with _X_ marking the percentage value of the progress bar. For example: `echo "UPDATE_PROGRESS_15"`
To show a specific message to the user some commands are also available. The following lines can be added to the script:
```bash
echo "UPDATE_MESSAGE_your message"
echo "UPDATE_WARNING_your warning"
echo "UPDATE_ERROR_your error"
```
This will show the message in either green, yellow or red respectively based on if you use a normal, warning or error message.
An example script using this is for example:
```bash
#!/usr/bin/env bash
echo "UPDATE_MESSAGE_Starting the online installation script!"
echo "UPDATE_PROGRESS_15"
python3 -m pip install mypythondependency
cd $1
git clone "https://${2}:${3}@cosysgit.uantwerpen.be/rtis-software/rtissoftware.git"
echo "UPDATE_MESSAGE_This is my message"
echo "UPDATE_WARNING_This is my warning"
echo "UPDATE_ERROR_This is my error"
echo "UPDATE_PROGRESS_50"
echo "UPDATE_MESSAGE_Execution done!"
echo "UPDATE_PROGRESS_100"
```
Another example is how to get the current Python version:
```bash
PY_VER_MAJOR="0"
PY_VER_MINOR="0"
if which python3 > /dev/null 2>&1;
then
PY_VER_MAJOR="$(python3 -c 'import sys; print(sys.version_info[0])')"
PY_VER_MINOR="$(python3 -c 'import sys; print(sys.version_info[1])')"
fi
if [ "${PY_VER_MAJOR}" = "3" ];
then
if [ "${PY_VER_MINOR}" == "6" ];
then
echo "UPDATE_MESSAGE_Python v3.6 detected."
else
echo "UPDATE_ERROR_Python installation found but is not version 3.6. Please install python 3.6."
exit 1
fi
else
echo "UPDATE_ERROR_Python installation not found with command 'python3'. Please install python 3.6."
exit 1
fi
```
To see if a Python module is installed you can use some code like this example:
```bash
if python3 -c "import rtisdev" > /dev/null 2>&1 -eq 0;
then
echo "UPDATE_MESSAGE_RTIS Dev module found!"
else
echo "UPDATE_ERROR_RTIS Dev module not found, install it!"
fi
```
### Firmware installation
Currently only supported on Jetson devices, the RTIS device firmware can also be updated online using _stm32loader_ and _Jetson.GPIO_.
This requires some particular attributes in the [online JSON description](#online-json-descriptions) file.
The update name and attribute `type` should always be set to `firmware`.
The `installation_script` has to be set to the download URL where the firmware binary file can be retrieved.
Furthermore, the binary firmware file should also be present in the patch archive as well as defined in the JSON description under the `filename` attribute.
Finally, you can optionally add the `port` attribute to override the automatic detection of the right port as well as customize the stm32 switch-pin with the `stm32pin` attribute (default=7).
An example JSON description:
```json
{
"firmware": {
"name": "RTIS Device Firmware",
"version": "1.5.0",
"type": "firmware",
"filename": "v1.5.0.bin",
"port": "/dev/ttyTHS2",
"stm32pin": 9,
"installation_script": "https://cosysgit.uantwerpen.be/rtis-software/rtisupdate/uploads/v1.5.0.bin"
}
}
```
### Self-upgrade
RTIS update can also update itself, even online. This works rather similarly to the other online updates but requires some particular things to work correctly.
The update name in the [online JSON description](#online-json-descriptions) file should always be `rtisupdate` as this is in the backend hardcoded to be the name of the RTIS Update self-upgrade package.
Furthermore, the version is similarly checked to be higher based on what is listed in the `patch_software.json` file.
A example JSON description:
```json
{
"rtisupdate": {
"name": "RTIS Update",
"version": "5.0.0",
"repo": "https://cosysgit.uantwerpen.be/rtis-software/rtisupdate",
"wiki": "https://cosysgit.uantwerpen.be/rtis-software/rtisupdate/-/wikis/home",
"doc": "README.md",
"installation_script":"https://cosysgit.uantwerpen.be/rtis-software/rtisupdate/-/snippets/30/raw/main",
"git_required": 1
}
}
```
The `installation.sh` and `installation.ps1` scripts should install/restart the service that runs RTIS Update in the background.
This script is always launched with arguments that will contain the same launch arguments as the currently running script.
For example on Windows and Linux respectively you can use:
```powershell
echo "RTIS Update online installation script for Windows Systems"
$install_folder = $args[0]
$gitusername = $args[1]
$gitpassword = $args[2]
$reponame = "https://" + $gitusername + ":" + $gitpassword + "@cosysgit.uantwerpen.be/rtis-software/rtisupdate"
git pull $reponame
if(get-service rtisupdate){
echo " RTIS Update Service..."
Restart-Service -Name rtisupdate -Force
echo "RTIS Update Service restarted!"
}
echo "Installation completed!"
```
```bash
#!/usr/bin/env bash
echo "RTIS Update online installation script for Linux Systems"
git pull "https://${2}:${3}@cosysgit.uantwerpen.be/rtis-software/rtisupdate"
if systemctl cat rtisupdate;
then
echo " RTIS Update Service..."
service rtisupdate restart
echo "RTIS Update Service restarted!"
fi
echo "Installation completed!"
```
\ No newline at end of file