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
View page @ 0f1d3dd3
# RTIS Update
This script can be used to automatically install and/or update some base RTIS Software packages and their dependencies.
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 service can run offline and is therefore able to update RTIS devices without an active internet connection.
## Features
* Self-update: Once installed, this script can self-update through GIT when starting up the script.
* Install several RTIS Software packages: Dev, Serial, CUDA, Network, Utils and Dev Remote.
* The RTIS Dev, Serial and CUDA Python Modules will be automatically installed and/or updated.
* The RTIS Network, Utils and Dev Remote packages will optionally allow to install the automatic start-up service.
* All dependencies will be automatically installed.
* The user can optionally choose a custom version to be used for each package.
* The user can choose where the RTIS Network, Utils and Dev Remote packages are installed as well as which user is used for operating them.
* The web interface shows all currently tracked and installed software packages.
* New installation and updates are installed using `.rtispatch` files distributed by a Cosys-Lab member.
* Self-updating can make sure RTIS Update stays up to date.
* 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.
* The STM32 firmware of an RTIS device can be found and flashed.
* Services can be automatically installed and updated. Furthermore, these can be restarted/stopped through the 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.
## Usage
## Interface usage
To run the main updater script simply run the bash script from your terminal with sudo rights:
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 a 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.
### 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' or 'pythonmodule' currently]
"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, [0 or 1, if set to 1 it will be installed as an automatic-restart service. 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", [additional arguments can be given for Linux services (with supported parameter names)]
"environment": "LD_LIBRARY_PATH=/usr/lib/rtiscuda",
...
},
...
}
},
"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:
```shell
sudo ./RTISUpdate.sh
```
\ No newline at end of file
```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.
#### 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"
```
#### Linux Shell scripts
TODO
\ No newline at end of file