Setting up your virtual plant

Estimated time: 10–15 minutes

[info] Prerequisites

A basic understanding of the nio System Designer. You can complete the System Designer workshop to get oriented if needed.

An active nio account.

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.

Create your system

From the nio System Designer, create a new system by clicking the add new system card on the designer home page. Select tutorial: virtual plant as your system template.

This will create a system for you to use throughout this workshop. This system will consist of a cloud instance (which was just spun up automatically for you) and a local instance, which you will set up on your machine in a few minutes. Expand your system on the left navigation of the designer to see the two instances that were just created.

Your plant (a local nio instance)

You will need to create a local instance of nio on your machine and connect it to your newly created system. This local instance will function as a metaphor for the plant and the environmental conditions it is experiencing in this workshop.

Install nio locally

First things first, install your nio binary. Full instructions on how to do this can be found in the nio documentation on local installations, but here are the basics:

  1. Make sure you have Python 3.4 or greater installed on your machine. The nio installation docs provide some helpful links for this. There is also a good guide for installing Python on many different operating systems at
  2. Download your nio binary from the binary download page. Select the nio binary, it is a Python wheel. If you ever need to find this page again from the System Designer, you can click the "keypad menu" at the top right and select "binaries".
  3. Install your binary using pip - something like pip3 install nio_full-....whl depending on your binary filename.

Install the virtual plant project

If you haven't done this before, this is a good time to create a directory to store your nio projects. The nio command line interface was installed for you alongside nio, and is the recommended tool for creating a new project. Open a terminal or command prompt, and run these commands:

mkdir -p nio/projects
cd nio/projects

Now, from within your projects directory, run:

nio new virtual_plant -t demo_plant --no-ssl

[info] nio and SSL

The previous CLI command will not configure your instance with SSL. This is easier to set up for testing but once things get up and running we recommend running your instances with SSL certificates enabled. We have documentation on running your instance with SSL to help you through the process.

Run your nio instance

Finally we need to configure credentials to use the provided pubkeeper server, and then start the nio instance. The credentials are generated automatically as part of creating the new system:

  1. Click on the design icon on the far left of the System Designer
  2. Open the Edit System window
    • Locate the system that you created from template
    • Hover your mouse over its tile, don't click yet!
    • Click on the Edit icon on the lower left, it looks like a pen and paper
  3. We will need two values from the Edit System window, your hostname and token
  4. In your terminal, run the following command, substituting hostname and token with the values from the edit system modal. This command will configure your local instance to communicate with your cloud Pubkeeper server, thus adding it to your newly created system.
cd virtual_plant
nio config --pubkeeper-hostname=<hostname> --pubkeeper-token=<token>
  1. Once the instance is configured, you're ready to start it with this command

Your local nio instance is now running the virtual_plant project inside your terminal window, and you will see some log messages. Do not close this window, doing so or pressing Ctrl-C will stop the nio process.

Connect to your instance from the System Designer

  1. Select your system from the system tiles.
  2. Select the VirtualPlant instance from the left hand navigation
  3. You should see the services expand on the left nav and see a graph of services on the canvas now.

[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.

[info] http error

You may see a modal pop up indicating that there is an http error. This is indicating that you are trying to connect to an instance of nio that does not have HTTPS/SSL enabled but you are on an HTTPS web page. Browsers do not allow this. We expected this though by using the --no-ssl flag in our nio CLI command. The easiest solution is to use the non-https version of the System Designer located at by clicking use http in the error modal. You can also set up your instance with SSL by following [our documentation]( if you wish.

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 ""