🪴 Getting Started

Getting Started

Dependencies

Development

We officially only support Unix operating systems. Click on the "Use this template" button on the Ivy Repository (opens in a new tab) to start your own DAS repository:

Steps 1 through 5 of the development setup have been automated by running the following command. It will ask you for the necessary inputs:

# optional: change the Python interpreter to the one you want your DAS to run with
curl -s https://raw.githubusercontent.com/tum-esm/ivy/refs/heads/main/scripts/setup_development.py > /tmp/ivy_setup_development.py && python3 /tmp/ivy_setup_development.py

1. Clone your repository to your local machine

Replace myorg and myivy with your GitHub organization/user name, repository name, and the version you want to start with.

git clone https://github.com/myorg/myivy ~/Documents/myivy/dev

Also update these values in config/config.template.json and src/constants.py.

2. Navigate to the cloned directory and set up a virtual environment

cd ~/Documents/myivy/dev
python3 -m venv .venv
source .venv/bin/activate

3. Install the project dev dependencies

# using pip
pip install ".[dev]"
 
# or pdm
pdm sync --with dev
 
# or uv
uv sync --extra dev

4. Configure your local DAS

Use the config/config.template.json file as a starting point to create your own config/config.json file. Use https://tum-esm-ivy.netlify.app/api-reference/configuration (opens in a new tab) as a reference to see all available configuration options.

cp config/config.template.json config/config.json
# now edit config/config.json

5. Run the quick tests to check your setup

Check the tool in general (static types, docs, unit tests, etc.):

scripts/run_tests_quick.sh

6. Run the integration tests to fully validate your setup

If a backend is configured, you need to connecting to an MQTT broker running locally or in the cloud. The default backend config points to the local MQTT broker. Available scripts:

# start local MQTT server (you need to have mosquitto installed)
scripts/mosquitto_start.sh
 
# test whether the broker is running
scripts/mosquitto_test.sh
 
# stop local MQTT server
scripts/mosquitto_stop.sh
 
# alternatively, run a local thingsboard instance with docker (you need to have docker installed)
scripts/run_thingsboard.sh

Check the integrity of the local setup (the local config, connection to the configured repository, connection to the configured backend if configured):

scripts/run_tests_integration.sh

7. Run the local DAS

# in the foreground
python run.py
 
# or the background
python cli.py start

8. Observe the outputs of the system

You can see the output of your DAS in data/logs and data/messages.

If you have set up a backend, then you can observe the data and logs being published to the MQTT server:

  • For Tenta: logs/{system_identifier} and measurements/{system_identifier}
  • For ThingsBoard: v1/devices/me/telemetry

This page describes how to set up one of these backends: https://tum-esm-ivy.netlify.app/backends/general (opens in a new tab)

9. Update and build the documentation

The documentation is located in docs, organized using Nextra (opens in a new tab) and set up using Bun (opens in a new tab).

cd docs
 
# install dependencies (`npm install` also works)
bun install
 
# start a local development server
bun run dev

Build and publish the documentation on a static site hosting service:

bun run build

The static build is contained in docs/out.

10. Add your sensor-network specific code to the DAS

Get yourself familiar with the documentation on the core concepts of Ivy (opens in a new tab), its interfaces (opens in a new tab), and how it connects to IoT Backends (opens in a new tab). You can start with the overview section (opens in a new tab), giving you a brief description of the different components of Ivy.

Ivy is made to be owned, so feel free to strip away everything you don't use. You can remove the Ivy-specific parts of the documentation and just link to the central Ivy documentation (https://tum-esm-ivy.netlify.app/ (opens in a new tab)). We are happy to include your additions to the Ivy template - and of course, list you as a contributor.

11. Test a new version of your DAS

Make sure that all tests are passing. In the GitHub Actions CI, everything is already set up, so we recommend using it. You can still run the tests locally, if you have installed mosquitto on your system:

# start local MQTT server which is required for the CI tests have
scripts/mosquitto_start.sh
 
# test whether the broker is running
scripts/mosquitto_test.sh
 
# run all non-integration tests
scripts/run_tests_ci.sh
 
# stop local MQTT server
scripts/mosquitto_stop.sh

For these updater tests to work, your Ivy root directory (~/Documents/myivy) has to be empty to ensure that nothing is overwritten – this is why we recommend just running these tests in the CI environment. The updater test will set up the current setup twice under ~/Documents/myivy/myivy/1.2.3 and ~/Documents/myivy/myivy/4.5.6, run the first version regularly, and try to update it to the second version. This proves that the current codebase can be updated from and to.

12. Publish a new release

git tag v0.3.4
git push origin v0.3.4

Set up a new Production System

1. Set up the computer running the DAS (e.g., a Raspberry Pi)

Use a Unix operating system and install Python (opens in a new tab) version 3.10 or higher and git (opens in a new tab).

2. Run the production setup script

Define your environment:

export IVY_PROJECT_NAME="myivy"
export IVY_GIT_REPOSITORY="https://github.com/myorg/myivy"
export IVY_GIT_PROVIDER="github"  # or "gitlab"
export IVY_VERSION="1.1.0"
export IVY_SYSTEM_IDENTIFIER="my-das-node-076"
export IVY_CONFIG_FILEPATH="/someusbstick/config-system-076.json"
export IVY_PACKAGE_MANAGER="pdm"

Setup the production node:

# optional: change the Python interpreter to the one you want your DAS to run with
curl -s https://raw.githubusercontent.com/tum-esm/ivy/refs/heads/main/scripts/setup_production.py > /tmp/ivy_setup_production.py && python3 /tmp/ivy_setup_production.py

The script will print a line like * * * ... -cli.sh to be added to the crontab. This will restart the DAS after any crash, system reboot, or any software update or configuration change of your DAS. Then DAS will start running in the background in the next minute.

🌱 Introduction🌳 Overview