Maintenance Guide

Purpose

The purpose of this document is to enable the maintainers of this project to develop changes for the solution.

Development

Configuration of developer machine

The following should be installed in order to develop on OS2iot. It is assumed a Windows laptop is used.

  1. Docker Desktop

  2. Visual Studio Code with the following extensions:

    1. ESLint

    2. Npm

    3. Jest

    4. Prettier

  3. Pgadmin

  4. Git/Git Extensions/Sourcetree/Sublime Merge

Mac: In order to run os2iot-backend outside docker and connect to docker (run it via vs code) one must follow the steps below:

  • Add docker to hosts on mac

  • Run: sudo vim /etc/hosts

  • In vim type i to insert

  • Add line with ip and hosts.docker.internal e.g. 127.0.0.1 hosts.docker.internal

  • type: esc :wq to save and exit

  • start os2iot-backend in vs code via the terminal: npm run start

Source Code

Github is used to store the source code for the OS2iot project. It uses the following repositories:

Requirements

Setup developement

To setup your dev environment please follow these instructions:

  1. Get the solution from Github. Clone the OS2IoT-docker, OS2IoT-backend, and OS2IoT-frontend.

  2. Install typescript and angular globally on your computer. a. Angular 9 – install by open terminal and type npm install -g @angular/cli b. Typescript – install by open terminal and type npm install -g typescript

  3. For OS2IoT-frontend install dependencies and start a. Navigate terminal to the OS2IoT-frontend folder and type npm install

  4. For OS2IoT-backend install dependencies and start a. Navigate terminal to the OS2IoT-backend folder and type npm install

Starting dependencies for development

  1. (windows) Add os2iot-docker to file share in docker

    1. Open Docker Desktop -> Settings -> Resources -> FILE SHARING -> add os2iot-docker as shared folder.

  2. Open terminal and go to path of OS2IoT-docker and write

    docker-compose up chirpstack postgresql postgresChirpstackV4 chirpstack-gateway-bridge mosquitto-os2iot mosquitto redis os2iot-kafka os2iot-postgresql os2iot-zookeeper

  3. To quit: In your terminal you can press Ctrl + C twice. This will safely shut down docker.

Troubleshooting

Creation of multicasts:

Before the Chirpstack update to Chirpstack V4, the creation of multicast devices in a multicast group was based on Service Profiles, but since Service Profiles are not part of Chirpstack V4, it is now based on the application under which your devices are created. If your devices are under the same application in OS2IoT, but you still encounter errors during creation, it may be because your devices were created in Chirpstack V3. In that case, the devices need to be created with the same Service Profile they had at the time of their creation.

For more troubleshooting help see the installation guide.

Starting the frontend and backend for development

  1. Open the OS2IoT-frontend in visual studio code and start angular using: npm start

  2. Open the OS2IoT-backend in another instance of visual studio code and start it using npm start

Database

To access the database, using PGAdmin is recommended. The default credential can be seen in Users Notes.

Map

OS2IoT maps are running on the Leafletjs framework: https://leafletjs.com/. The tiles are current presented using OpenStreetMap: https://www.openstreetmap.org.

The tiles can be changed by following the steps listed below:

  1. Find “map.component.ts” in the frontend project

  2. Within the initMap() method, replace L.tileLayer(’https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png’) with the desired tiles

    1. Make sure you also change the attribution attribute.

Note that the solution must be deployed before the changes takes presence.

Debugging

Debugging the frontend

Use the debugger for chrome plugin to enable debugging in Chrome, follow the upto-date instruction in their readme.

Debugging the backend

Use the built in debugging, after launching using the launch.json configuration.

Branching strategy

OS2IoT uses git and GitFlow https://datasift.github.io/gitflow/IntroducingGitFlow.html for source code version control.

Naming Convention of branches

Naming feature branches follows standard: feature/branch-name, i.e. feature/IOT-1337.

Naming the hotfix branches follows standard: hotfix/branch-name, i.e. hotfix/IOT-1337.

Format of commit message

A commit must follow the format: [Story ID]: Message. For example: “IOT-1337: Update CreateUserDto to validate birthdays”

By starting commit messages with [Story ID], traceability is obtained from the code and to the case.

Tools

Chirpstack

Chirpstack is bundled as part of OS2IoT-docker.

The Chirpstack gRPC Protocol documentation can be found at: https://www.chirpstack.io/docs/chirpstack/api/api.html

For installation configuration of Chirpstack see: https://www.chirpstack.io/docs/chirpstack/configuration.html

Migrations

This project is using TypeORM migrations when changes are applied to the database. This is recommended by TypeORM when the project is used for production.

Generate migrations

If you modify or adds an entity (or more than one entity) and/or relationships you then need to generate a migration. In the console you write: npm run generate-migration <your name of the migration>. Then a migration file will be created in a migration folder. The folder path is specified in ormconfig.json. A timestamp will be added to the name to indicate when the migration has been generated. If no changes have been made to the entity classes, no migrations are generated.

Run migrations

When the project is starting, a new command will be called automatically. This happens every time you run the program because of a prestart script. The command is run-migrations which runs all the pending generated migrations in the Migrations folder, starting from the oldest migration. In the pending migrations, the up block will be executed. If there are no pending migrations then no migrations will be run.

It will happen in both debug and prod mode.

Revert migration

If you want to revert a migration later, you can write npm run typeorm migration:revert. Then the latest executed migration will be reverted. What happens is that the down block in the latest executed migration will be run. You can continue to do this until you reach the desired migration. The generated migrations will not be deleted when you are reverting so when you run the project again, the migrations will be run with the up block unless you manually deletes them.

Show migration

If you are in doubt which migrations has been run, then you have the possibility to write npm run typeorm migration:show in the console. Then the migrations will be shown in the console, and if [X] is marked at a migration it means that it has been run. Otherwise it will be an empty [] which means that is has NOT been run.

Maintaining the docs

To update the documentation, i.e. these pages you are reading now, you must edit the OS2IoT-docs Git repository: https://github.com/OS2iot/Os2iot-docs

The documentation is written in reStructuredText, see https://docutils.sourceforge.io/rst.html for an intro.

Building locally

  1. Make sure that you have Python installed, and that it is available in PATH

  2. Run: pip install -r requirements.txt

  3. Run: make html to generate the docs once or sphinx-autobuild source build to rebuild contentiously. a. The generated documentation can be found in /build/html/index.html or on the link shown in the CLI if using sphinx-autobuild

  4. For spelling check you can install “Code Spell Checker” assuming that you run Visual Code.

ReadTheDocs will automatically pull changes pushed to the master branch and build it.