Setting up your virtual plant

Estimated time: 10–15 minutes

[info] Prerequisites

A basic understanding of the nio System Designer.

A nio system in the System Designer.

If you haven't created a system, this tutorial is available as the tutorial 2: virtual plant system template. To access the system template, follow the instructions here:

A few core principles of the nio Platform can be learned by monitoring and managing a plant's environment. All plants need water, so the "goal" of this system will be to maintain a sufficient moisture level for your plant to thrive.

This mini-ecosystem will consist of the following distributed elements:

  1. The plant: a local nio instance
  2. The UI: a cloud based user interface
  3. The weather: a cloud nio instance (introduced in the Extra credit: Weather workshop)
  4. Pubkeeper server: the system's communications broker (learn more)

Next, create and configure the plant and UI, step-by-step.

Your plant (a local nio instance)

Your local nio instance functions as a metaphor for both the plant and the environmental conditions it's experiencing:

  • Current soil moisture percentage
  • Water in:
    • Irrigation rate
    • Rain rate
  • Water out:
    • Soil evaporation rate

In a real-life precision agriculture system, the plants would be less metaphorical. And to monitor a whole orchard or vineyard, multiple nio instances would run on edge nodes connected to pumps, valves, and sensors.

Start a new local instance of nio to serve as your metaphorical plant.

Install nio locally

[info] Requirements

Linux / MacOS

Windows users, click here for installation instructions.

Navigate to, agree to the license, and download the correct nio binary for your system.

[info] Windows users

Windows users should download the Windows Installer. Double-click and follow the prompts. Specific Windows installation instructions can be found here:

Open a terminal (Applications > Utilities > Terminal on MacOS), and install nio using Python’s pip3 installer (verify the filepath and binary filename below—the Xs represent the date of the binary in YYYYMMDD format):

pip3 install -U ~/Downloads/nio_lite-XXXXXXXX-py3-none-any.whl

MacOS Users: You may be prompted to install a dependency called "clang". This is a standard component that comes directly from Apple, so it's safe to click "OK" and re-run the command above.

You can test that nio is correctly installed by running the following command:

which niod

If you don’t see a path to niod, make sure Python’s binary directory is on your PATH.

Help setting your PATH: Windows / MacOS.

Install the virtual plant project

nio new my_plant -t demo_plant
  1. You will first be prompted for your Pubkeeper hostname and token. The values are part of the system you created in the System Designer. To locate these values:
    • Open the System Designer in a browser: (note the http protocol, used for installed local instances without SSL certificates).
    • Hover over your system in the grid of cards and click the edit button in the toolbar to open its configuration.
    • Copy and paste the values for hostname and token when prompted in the terminal.
  2. The final prompt will ask if you want an Optional secure instance configuration. Click enter to accept No as the default.

Run your nio instance

In your terminal, change directories and navigate into your my_plant directory by typing

cd my_plant

From your my_plant directory, type niod into your terminal to start the nio instance.


Add your local (running) instance to the System Designer

If you created your system with the virtual plant system template:

Click your system name and then the VirtualPlant instance.

If you did not use the virtual plant system template:

  1. Open the System Designer in a browser:
  2. Select your system from the grid of cards.
  3. Click add instance.
    • Check the local instance checkbox.
    • In the instance name box, enter VirtualPlant.
    • Leave the other default values in the window.
  4. Click accept.

[info] Do you want to continue?

You may see a window telling you to check your local instance while the nio System Designer connects to your local instance. If you see this window it means you have connected to a previous local instance with the same connection properties. Check the box next to connect anyways and click accept.

You should now see the seven pre-loaded nio services in your local VirtualPlant instance:

[warning] Where are my services?

If you don't see the services, they may not be centered on the canvas. Click the "center" button to auto position the services ().

Explore the services in your VirtualPlant instance

In the service list in the left navigation, two of the services are already running (they have little triangles next to their labels instead of squares). Look at those services first.


In nature, water evaporates at certain rates based on soil type, weather, and other factors. Conversely, soil absorbs rain and irrigation at certain rates depending on the application rate and the similar environmental factors. This service plays the role of mother nature and sets those rates with fixed values to simulate what happens in the real world.

Click the Environment_Variables service name in the service list to switch to the service context and view the service configuration in the canvas. This service contains three blocks in a line from top to bottom:

  • TimeInterval
  • FieldParameters
  • ToPlant

The first and last blocks of this service have the same function as the two blocks in the simulate-and-log service you created in the System Designer workshop. The first block, TimeInterval, is a simulator/generator block that drives your service. The last block, ToPlant, is a Publisher block, that, in place of a Logger block, allows data to easily flow between nio services and instances.

The middle block adds something new. The FieldParameters block sets three rates:

Evaporation = -0.1% / second
Rain absorption = 0.3% / second
Irrigation absorption = 1.0% / second

Double click the FieldParameters block to open its configuration and see how those variables are set.


Click the Plant_Simulator service name in the service list to view its configuration in the canvas.

This service is a bit more complicated, but it represents all the components of a typical farm:

  1. The plant itself
  2. Various sensors (soil moisture, pressure, flow)
  3. The irrigation delivery infrastructure (pump and valves)

The Plant_Simulator service subscribes to the simulated rates published from the Environment_Variables service, then ingests and evaporates water to and from your plant's soil—hopefully at a ratio that your plant finds enjoyable. If not, use nio to ensure your plant remains content.

The UI (a cloud-based user interface)

The ability to apply real-time logic and automation throughout a system is what nio is all about. But it's hard for (non-robot) humans to visualize and control distributed systems if they can't see what's going on. The UI will allow you to monitor your plant in real time, as well as deliver water to it when needed.

With nio, user interfaces (UIs) are first-class citizens of distributed systems. Rather than sending all data to a cloud server or database (how most solutions are built today), nio's communications broker, Pubkeeper, allows UIs to subscribe directly to signals.

To set up your UI, navigate to, log in, and select your system.

You should see something like this:

  1. Your plant
  2. A toggle button to control your irrigation
  3. The current soil moisture
  4. A historical soil moisture graph

Water your plant

Toggle the irrigation on using the button at the top of the screen. The soil moisture will begin to increase at a rate of 0.9% per second (1% absorption rate minus 0.1% evaporation rate–the values set in the Environment_Variables service). Once it reaches 100%, it will be at max capacity and will stop increasing.

If you toggle irrigation off using the same button, you'll see the water evaporate at 0.1% per second.

What is happening?

  • nio is using "sensors" in the Plant_Simulator service to measure the soil moisture of the plant. The service then publishes the soil moisture data. The UI subscribes to it, and displays it in real time.

  • When you toggle irrigation on, the UI publishes a signal indicating that you want to start watering. The IrrigationCommands Subscriber block in your Plant_Simulator service is listening for (subscribing to) just such a signal and, upon receiving it, turns on the simulated pump, opens the simulated valve, and simulates irrigating the plant.

  • Toggling irrigation off, sends the opposite signal, which triggers the local nio instance to close the simulated valve, turn off the simulated pump, and stop irrigating. All the while, the local nio instance continues to monitor the real-time soil moisture.

[info] Learn more about pub/sub

The communication method used within nio systems is called pub/sub, which stands for publish/subscribe.

Learn about publishing and subscribing to topics in the next section, data storage.

Set up your own publishers and subscribers and learn how to keep track of your topics in the streaming API and merging streams tutorials.

You can water your plant by clicking a toggle switch, but your service is not very automated.

Add automation

Each of the remaining five services on your local instance use the soil moisture percentage output from the Plant_Simulator service to solve the most pressing problem of the modern age: keeping your plant alive without having to personally monitor its status.

In the next section, you'll learn how to use historical data to keep your plant alive with nio.


proceed to solution #1: data storage »

results matching ""

    No results matching ""