Virtual Single-Board Computer

Instead of buying an IoT device with sensors and actuators, you can simulate IoT hardware using your computer. The CounterFit project enables you to run a local app that emulates IoT hardware like sensors and actuators. You can access these sensors and actuators from local Python code, written similarly to the code you would use on a Raspberry Pi with physical hardware.

Setup

To get started with CounterFit, you need to install some free software on your computer.

Task

Install the necessary software.

1. Install Python. Visit the Python downloads page for instructions on installing the latest version of Python.

2. Install Visual Studio Code (VS Code). This is the editor you will use to write your virtual device code in Python. Refer to the VS Code documentation for installation instructions.

   💁 You can use any Python IDE or editor for these lessons if you prefer, but the instructions will be based on using VS Code.

3. Install the VS Code Pylance extension. This extension provides Python language support in VS Code. Refer to the Pylance extension documentation for installation instructions.

Instructions for installing and configuring the CounterFit app will be provided at the appropriate time in the assignment instructions, as it is installed on a per-project basis.

Hello World

When starting with a new programming language or technology, it is customary to create a 'Hello World' application. This small application outputs text like "Hello World" to confirm that all tools are correctly configured.

The Hello World app for virtual IoT hardware will ensure that you have Python and Visual Studio Code installed correctly. It will also connect to CounterFit for virtual IoT sensors and actuators. No hardware will be used; it will just connect to verify everything is working.

This app will be in a folder called nightlight, and it will be reused with different code in later parts of this assignment to build the nightlight application.

Configure a Python Virtual Environment

One of Python's powerful features is the ability to install Pip packages - packages of code written by others and published online. You can install a Pip package on your computer with one command and use it in your code. You'll use Pip to install a package to communicate with CounterFit.

By default, when you install a package, it is available everywhere on your computer, which can lead to version conflicts. One application might depend on one version of a package that breaks when you install a new version for another application. To avoid this, you can use a Python virtual environment, essentially a copy of Python in a dedicated folder. When you install Pip packages, they are installed only in that folder.

💁 If you are using a Raspberry Pi, you didn't set up a virtual environment on that device to manage Pip packages. Instead, you are using global packages, as the Grove packages are installed globally by the installer script.

Task - Configure a Python Virtual Environment

Set up a Python virtual environment and install the Pip packages for CounterFit.

1. From your terminal or command line, run the following commands at a location of your choice to create and navigate to a new directory:

   mkdir nightlight
   cd nightlight

2. Now run the following command to create a virtual environment in the .venv folder:

   python3 -m venv .venv

   💁 You need to explicitly call python3 to create the virtual environment in case you have Python 2 installed in addition to Python 3 (the latest version). If you have Python 2 installed, calling python will use Python 2 instead of Python 3.

3. Activate the virtual environment:

   • On Windows:

     • If you are using the Command Prompt or the Command Prompt through Windows Terminal, run:

       .venv\Scripts\activate.bat

     • If you are using PowerShell, run:

       .\.venv\Scripts\Activate.ps1

       If you get an error about running scripts being disabled on this system, you need to enable running scripts by setting an appropriate execution policy. You can do this by launching PowerShell as an administrator and running the following command:

       Set-ExecutionPolicy -ExecutionPolicy Unrestricted

       Enter Y when asked to confirm. Then re-launch PowerShell and try again.

       You can reset this execution policy later if needed. You can read more about this in the Execution Policies page on Microsoft Docs.

   • On macOS or Linux, run:

     source ./.venv/bin/activate

   💁 These commands should be run from the same location where you ran the command to create the virtual environment. You will never need to navigate into the .venv folder. Always run the activate command and any commands to install packages or run code from the folder you were in when you created the virtual environment.

4. Once the virtual environment is activated, the default python command will run the version of Python used to create the virtual environment. Run the following command to get the version:

   python --version

   The output should be similar to the following:

   (.venv) ➜  nightlight python --version
   Python 3.9.1

   💁 Your Python version may be different. As long as it's version 3.6 or higher, you are good. If not, delete this folder, install a newer version of Python, and try again.

5. Run the following commands to install the Pip packages for CounterFit. These packages include the main CounterFit app and shims for Grove hardware. These shims allow you to write code as if you were programming with physical sensors and actuators from the Grove ecosystem but connected to virtual IoT devices.

   pip install CounterFit
   pip install counterfit-connection
   pip install counterfit-shims-grove

   These Pip packages will only be installed in the virtual environment and will not be available outside of it.

Write the Code

Once the Python virtual environment is ready, you can write the code for the 'Hello World' application.

Task - Write the Code

Create a Python application to print "Hello World" to the console.

1. From your terminal or command line, run the following command inside the virtual environment to create a Python file called app.py:

   • On Windows, run:

     type nul > app.py

   • On macOS or Linux, run:

     touch app.py

2. Open the current folder in VS Code:

   code .

   💁 If your terminal returns command not found on macOS, it means VS Code has not been added to your PATH. You can add VS Code to your PATH by following the instructions in the Launching from the command line section of the VS Code documentation and run the command afterward. VS Code is installed to your PATH by default on Windows and Linux.

3. When VS Code launches, it will activate the Python virtual environment. The selected virtual environment will appear in the bottom status bar:

   

4. If the VS Code Terminal is already running when VS Code starts up, it won't have the virtual environment activated in it. The easiest thing to do is kill the terminal using the Kill the active terminal instance button:

   

   You can tell if the terminal has the virtual environment activated as the name of the virtual environment will be a prefix on the terminal prompt. For example, it might be:

   (.venv) ➜  nightlight

   If you don't have .venv as a prefix on the prompt, the virtual environment is not active in the terminal.

5. Launch a new VS Code Terminal by selecting Terminal -> New Terminal, or pressing CTRL+`. The new terminal will load the virtual environment, and the call to activate this will appear in the terminal. The prompt will also have the name of the virtual environment (.venv):

   ➜  nightlight source .venv/bin/activate
   (.venv) ➜  nightlight 

6. Open the app.py file from the VS Code explorer and add the following code:

   print('Hello World!')

   The print function prints whatever is passed to it to the console.

7. From the VS Code terminal, run the following command to run your Python app:

   python app.py

   The following will be in the output:

   (.venv) ➜  nightlight python app.py 
   Hello World!

😀 Your 'Hello World' program was a success!

Connect the 'Hardware'

As a second 'Hello World' step, you will run the CounterFit app and connect your code to it. This is the virtual equivalent of plugging in some IoT hardware to a dev kit.

Task - Connect the 'Hardware'

1. From the VS Code terminal, launch the CounterFit app with the following command:

   counterfit

   The app will start running and open in your web browser:

   

   It will be marked as Disconnected, with the LED in the top-right corner turned off.

2. Add the following code to the top of app.py:

   from counterfit_connection import CounterFitConnection
   CounterFitConnection.init('127.0.0.1', 5000)

   This code imports the CounterFitConnection class from the counterfit_connection module, which comes from the counterfit-connection pip package you installed earlier. It then initializes a connection to the CounterFit app running on 127.0.0.1, which is an IP address you can always use to access your local computer (often referred to as localhost), on port 5000.

   💁 If you have other apps running on port 5000, you can change this by updating the port in the code and running CounterFit using CounterFit --port <port_number>, replacing <port_number> with the port you want to use.

3. You will need to launch a new VS Code terminal by selecting the Create a new integrated terminal button. This is because the CounterFit app is running in the current terminal.

   

4. In this new terminal, run the app.py file as before. The status of CounterFit will change to Connected and the LED will light up.

   

💁 You can find this code in the code/virtual-device folder.

😀 Your connection to the hardware was a success!