This the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Software

Software collection for a variety of Raspberry PI general and special purpose clusters.

Here we collect some software that relates to cluster computing and PI’s.

1 - Autogenerating Analytics Rest Services

In this section, we will deploy a Pipeline Anova SVM API on an openapi service using cloudmesh-openapi

Learning Objective

We will learn to create a REST service automatically from pyton functionsq with the help of cloudmesh-openapi. We use as example a Pipeline Anova SVM from which we generate an openapi server, and subsequently train the model with data and make predictions from said data. All code needed for this is provided in the cloudmesh-openapi repository. The code is largely based on this sklearn example. This includes

  • Training ML models with stateless requests
  • Generating RESTful APIs using cms openapi for existing python code
  • Deploying openapi definitions onto a localserver
  • Interacting with newly created openapi services

Topics Covered

1. Prerequisite

It is also assumed that the user has installed and has familiarity with the following:

  • Install cloudmesh-openapi using the developer install as documented here
  • Python 3.8.x
  • Linux Command line
  • Working in a python environment

2. The Python Code

First, let us ensure we are in the correct directory. If you followed the cloudmesh-openapi installation directions as dictated in the installation guide, simply navigate to the root directory of cloudmesh-openapi. Notice how we are still working in our python virtual environment ENV3 from the installation guide.

(ENV3) > pwd
~/cm/cloudmesh-openapi

Let us take a look at the PipelineAnova SVM example code.

A Pipeline is a pipeline of transformations to apply with a final estimator. Analysis of variance (ANOVA) is used for feature selection. A Support vector machine SVM is used as the actual learning model on the features.

Use your favorite editor to look at it (whether it be vscode, vim, nano, etc). We will use emacs

(ENV3) > emacs ./tests/Scikitlearn-experimental/sklearn_svm.py

The class within this file has two main methods to interact with (except for the file upload capability which is added at runtime)

@classmethod
def train(cls, filename: str) -> str:
    """
    Given the filename of an uploaded file, train a PipelineAnovaSVM
    model from the data. Assumption of data is the classifications 
    are in the last column of the data.

    Returns the classification report of the test split
    """
    # some code...

@classmethod
def make_prediction(cls, model_name: str, params: str):
    """
    Make a prediction based on training configuration
    """
    # some code...

Note the parameters that each of these methods takes in. These parameters are expected as part of the stateless request for each method.

3. Generating the OpenAPI YAML file

Let us now use the python code from above to create the openapi YAML file that we will deploy onto our server. To correctly generate this file, use the following command:

(ENV3) > cms openapi generate PipelineAnovaSVM 
    \ --filename=./tests/Scikitlearn-experimental/sklearn_svm.py
    \ --import_class
    \ --enable_upload

Let us digest the options we have specified:

  • --filename indicates the path to the python file in which our code is located
  • --import_class notifies cms openapi that the YAML file is generated from a class. The name of this class is specified as PipelineAnovaSVM
  • --enable_upload allows the user to upload files to be stored on the server for reference. This flag causes cms openapi to auto-generate a new python file with the upload method appended to the end of the file. For this example, you will notice a new file has been added in the same directory as sklearn_svm.py. The file is aptly called: sklearn_svm_upload-enabled.py

4. The OpenAPI YAML File (optional)

If Section 2 above was correctly, cms will have generated the corresponding openapi YAML file. Let us take a look at it.

(ENV3) > emacs ./tests/Scikitlearn-experimental/sklearn_svm.yaml

This YAML file has a lot of information to digest. The basic structure is documented here. However, it is not necessary to understand this information to deploy RESTful APIs.

However, take a look at paths: on line 9 in this file. Under this section, we have several different endpoints for our API listed. Notice the correlation between the endpoints and the python file we generated from.

5. Starting the Server

Using the YAML file from Section 2, we can now start the server.

(ENV3) > cms openapi server start ./tests/Scikitlearn-experimental/sklearn_svm.yaml

The server should now be active. Navigate to http://localhost:8080/cloudmesh/ui.

Unavailable

6. Interacting With the Endpoints

6.1 Uploading the Dataset

We now have a nice user inteface to interact with our newly generated API. Let us upload the data set. We are going to use the iris data set in this example. We have provided it for you to use. Simply navigate to the /upload endpoint by clicking on it, then click Try it out.

We can now upload the file. Click on Choose File and upload the data set located at ./tests/Scikitlearn-experimental/iris.data. Simply hit Execute after the file is uploaded. We should then get a 200 return code (telling us that everything went ok).

Unavaialable

6.2 Training on the Dataset

The server now has our dataset. Let us now navigate to the /train endpoint by, again, clicking on it. Similarly, click Try it out. The parameter being asked for is the filename. The filename we are interested in is iris.data. Then click execute. We should get another 200 return code with a Classification Report in the Response Body.

Unavailable

6.3 Making Predictions

We now have a trained model on the iris data set. Let us now use it to make predictions. The model expects 4 attribute values: sepal length, seapl width, petal length, and petal width. Let us use the values 5.1, 3.5, 1.4, 0.2 as our attributes. The expected classification is Iris-setosa.

Navigate to the /make_prediction endpoint as we have with other endpoints. Again, let us Try it out. We need to provide the name of the model and the params (attribute values). For the model name, our model is aptly called iris (based on the name of the data set).

Unavailable

As expected, we have a classification of Iris-setosa.

7. Clean Up (optional)

At this point, we have created and trained a model using cms openapi. After satisfactory use, we can shut down the server. Let us check what we have running.

(ENV3) > cms openapi server ps
openapi server ps

INFO: Running Cloudmesh OpenAPI Servers

...

[{'name': 'sklearn_svm', 'pid': 7496, 'spec': './tests/Scikitlearn-experimental/sklearn_svm.yaml'}]
+-------------+------+--------------------------------------------------+
| name        | pid  | spec                                             |
+-------------+------+--------------------------------------------------+
| sklearn_svm | 7496 | ./tests/Scikitlearn-                             |
|             |      | experimental/sklearn_svm.yaml                    |
+-------------+------+--------------------------------------------------+

We can stop the server with the following command:

(ENV3) > cms openapi server stop sklearn_svm

We can verify the server is shut down by running the ps command again.

(ENV3) > 
openapi server ps

INFO: Running Cloudmesh OpenAPI Servers

[]
None

8. Assignments

Many ML models follow the same basic process for training and testing:

  1. Upload Training Data
  2. Train the model
  3. Test the model

Using the PipelineAnovaSVM code as a template, write python code for a new model and deploy it as a RESTful API as we have done above. Train and test your model using the provided iris data set. There are plenty of examples that can be referenced here

9. References

2 - Link Collection abut PI Clusters and Parts

A number of links related to software to use PI’s and create clusters.

Learning Objectives

  • Get informed what resources exist

Topics covered

Software

OS

Booting and Startup

SDCard Creation

  • Cludhmesh Pi Burn Very good for burning multiple cars for clusters with easy setup of a cluster of PIs that are fully connected with each other.
  • Pi Imager, raspberrypi.org Best suited for burning individuall cards. Requires additional work after burning, such as setting hostname, and enable ssh. Time consuming when setting up a cluster.
  • Pi Bakery Easy setup of individual Pis, with the ability to add post instalation information such as Wifi, hostname and others. GUI driven. Not targeted towards Cluster setups.

PXE Boot

Network of Workstations

  • Cludhmesh Pi Burn Setting up a cluster of Pis easily including ssh, keys, and networking.

SLURM

MPI

Kubernetes

  • see our special section on kubernetes

Network Configurations

mDNS

Mesh Network

3 - Cloudmesh Pi Burner

Create easily preconfigured SDCards to make cluster setups easier.

Learning Objectives

  • Find an easier way to burn multiple SD Cards for clusters with preconfiguration included.

WARNING: This program is designed for a Raspberry Pi. Instructions to use Linux are included in the FAQ. We are working on support for macOS and Windows 10. If you want to help us port to any of these OSes, please contact laszewski@gmail.com

image image image License

Introduction

cms burn is a program to burn many SD cards for the preparation of building clusters with Raspberry Pi’s. It allows users to create readily bootable SD cards that have the network configured and contain a public ssh key from your machine that you used to configure the cards. Thus, little setup is needed for a cluster. Another unique feature is that you can burn multiple cards in a row, each with their individual setup such as hostnames and ipadresses.

Nomenclature

  • Commands proceeded with pi@mangerpi:$ are to be executed on the Rasperry Pi with the name managerpi.

  • Commands with (ENV3) pi@managerpi:$ are to be executed in a virtula ENV using Python 3 on the Raspberry Pi with the name managerpi

Quickstart for Bridged WiFi

To provide you with a glimpse on what you can do with cms burn, we have provided this quickstart guide that will create one manager PI and several workers.

This setup is intended for those who have restricted access to their home network (ie. cannot access router controls). For example, those on campus WiFis or regulated apartment WiFis.

The Figure 1 describes our network configuration. We have 5 Raspberry Pi 4s: 1 manager and 4 workers. We have WiFi access, but we do not necessarily have access to the router’s controls.

We also have a network switch, where the manager and workers can communicate locally, but we will also configure the manager to provide internet access to devices on the network switch via a “network bridge”.

Figure 1: Pi Cluster setup with bridge network

Requirements

For the quickstart we have the following requirements:

  • SD Cards and Raspberry Pis

  • You will need an SD card writer (USB-A) to burn new cards We recommend that you invest in a USB 3.0 SDCard writer as they are significantly faster and you can resuse them on PI'4s

Manager Pi

First we need to configure the Manager Pi

Step 0. Burn Manager Pi SD Card

Using Raspberry Pi imager, burn an SD card with Raspberry Pi OS (32-bit) with desktop and recommended applications. You may use your normal system to burn such a card including Windows, macOS, or Linux.

You will then want a method of accessing this manager Pi. You may either use SSH (recommended) or monitor desktop environment (easiest) to access it. We highly recommend changing the password on the Pi as soon as you have access. This is because the pi is initialized with default user pi and default password raspberry. This is critical if you are on a shared network where anyone can attempt to access your pi.

Monitor Desktop Environment: You will need a monitor, keyboard, and mouse. This is the easiest approach as Raspberry Pi OS provides a very nice user interface with an easy-to-follow setup process for connecting to WiFi and other such tasks.

SSH Environment: You may consider enabling SSH access to your Pi so that you may access the file system from your preferred machine.

Headless Configuration: See section 3 of enabling ssh for instructions on how to enable SSH headlessly. Similarly, how to enable WiFi headlessly. Additionally you can check out the FAQ for step-by-step instructions. Using Pi Imager to setup a Manager Pi with headless access.

Update the firmware: See the FAQ [How to update firmware?]> (#how-to-update-firmware)

Step 1. Installing Cloudmesh on the Manager Pi

Open a new terminal screen on the Manager Pi. Here we assume the hostname is managerpi. However, this is of no importance in relation to topics of this guide.

Update pip. The simple curl command below will generate an ssh-key, update your system, and install cloudmesh.

pi@managerpi:~ $ pip install pip -U
pi@managerpi:~ $ curl -Ls http://cloudmesh.github.io/get/pi | sh -

This will take a moment…

Step 2. Reboot

The installation script updates your system. Reboot for effect.

pi@managerpi:~ $ sudo reboot

Step 3. Download the latest Raspberry Pi Lite OS

The following command will download the latest images for Raspberry Lite OS.

(ENV3) pi@managerpi:~ $ cms burn image get latest-lite

We can verify our image’s downloaded with the following.

(ENV3) pi@managerpi:~ $ cms burn image ls

Note. For our cluster we use light, but if you like to use other versions please see this note. We can use the following command to list the current Raspberry Pi OS versions (full and lite)

(ENV3) pi@managerpi:~ $ cms burn image versions --refresh

This will list the Tags and Types of each available OS. We can then modify the image get command for versions we are interested in. For example,

(ENV3) pi@managerpi:~ $ cms burn image get full-2020-05-28

Step 4. Setup SD Card Writer

Plug your SD Card Writer into the Pi. Ensure you have an SD Card inserted into your writer. Run the following command to find the path to your SD Card.

(ENV3) pi@managerpi:~ $ cms burn info
...
# ----------------------------------------------------------------------
# SD Cards Found
# ----------------------------------------------------------------------

+----------+----------------------+----------+-----------+-------+------------------+---------+-----------+-----------+
| Path     | Info                 | Readable | Formatted | Empty | Size             | Aaccess | Removable | Writeable |
+----------+----------------------+----------+-----------+-------+------------------+---------+-----------+-----------+
| /dev/sda | Generic Mass-Storage | True     | True      | False | 64.1 GB/59.7 GiB | True    | True      |           |
+----------+----------------------+----------+-----------+-------+------------------+---------+-----------+-----------+

cms burn info has other useful information, but for the purposes of this guide we omit it.

We can see from the information displayed that our SD card’s path is /dev/sda. Of course, this may vary.

Burning Multiple SD Cards with a Single Burner

Step 0. Ensure the first SD card is inserted into the burner.

We can run cms burn info again as we did above to verify our SD card is connected.

Step 1. Burning the Cards

cms burn supports logical incremenation of numbers/characters.

For example, red00[1-2] is interpreted by cms burn as [red001, red002]. Similarly, red[a-c] is interpreted by cms burn as [reda, redb, redc].

We can burn 2 SD cards as follows:

!! WARNING VERIFY THE DEVICE IS CORRECT. REFER TO CMS BURN !!

(ENV3) pi@managerpi:~ $ cms burn create --hostname=red00[1-4] --ip=10.1.1.[2-5] --device=/dev/sda --tag=latest-lite

The user will be prompted to swap the SD cards after each card burn if there are still remaining cards to burn.

Step 2. Boot the cluster

After all cards are burned. Turn off the cluster, insert the cards, and turn the cluster back on.

We can now proceed to the next section where we configure our bridge.

Connecting Pis to the Internet via Bridge

Figure 1 depicts how the network is set up with the help of the bridge command.

Figure 1: Networking Bridge

Step 0. Review and Setup

At this point we assume that you have used cms burn to create all SD cards for the Pi’s with static IP addresses in the subnet range 10.1.1.0/24 (excluding 10.1.1.1. See step 1 for details)

We are also continuing to use managerpi (which is where we burn the worker SD cards).

We will now use cms bridge to connect the worker Pis to the internet. Let us again reference the diagram of our network setup. You should now begin connecting your Pis together via network switch (unmanaged or managed) if you have not done so already. Ensure that managerpi is also connected into the network switch.

We will assign the eth0 interface of the managerpi to be 10.1.1.1, and it will act as the default gateway for the workers. The workers IPs were set during the create command.

Step 1. Configuring our Bridge

We can easily create our bridge as follows.

(ENV3) pi@managerpi:~ $ cms bridge create --interface='wlan0'

We should now reboot.

(ENV3) pi@managerpi:~ $ sudo reboot

Note the --interface option indicates the interface used by the manager pi to access the internet. In this case, since we are using WiFi, it is likely wlan0. Other options such as eth0 and eth1 exist for ethernet connections.

Step 2. Verifying internet connection

We should now be able to see our workers.

arp -a

Note it may take a few minutes for them to populate in the neighbor table. If you want to speed this up try to ping them individually.

ping red001

At this point, our workers should have internet access. Let us SSH into one and ping google.com to verify. Ensure you have booted your workers and connected them to the same network switch as the manager.

(ENV3) pi@managerpi:~ $ ssh red001

pi@red001:~ $ ping google.com
PING google.com (142.250.64.238) 56(84) bytes of data.
64 bytes from mia07s57-in-f14.1e100.net (142.250.64.238): icmp_seq=1 ttl=106 time=48.2 ms
64 bytes from mia07s57-in-f14.1e100.net (142.250.64.238): icmp_seq=2 ttl=106 time=48.3 ms
64 bytes from mia07s57-in-f14.1e100.net (142.250.64.238): icmp_seq=3 ttl=106 time=47.9 ms
64 bytes from mia07s57-in-f14.1e100.net (142.250.64.238): icmp_seq=4 ttl=106 time=47.10 ms
64 bytes from mia07s57-in-f14.1e100.net (142.250.64.238): icmp_seq=5 ttl=106 time=48.5 ms
^C
--- google.com `ping statistics ---
5 packets transmitted, 5 received, 0% packet loss, time 9ms
rtt min/avg/max/mdev = 47.924/48.169/48.511/0.291 ms

Note how we are able to omit the pi user and .local extension. We have successfuly configured our bridge. Our pis are now ready to cluster.

Set up of the SSH keys and SSH tunnel

One important aspect of a cluster is to setup authentication via ssh in a convenient way, so we can easily login from the laptop to each of the PI workers and the PI manager. Furthermore, we like to be able to login from the PI manager to each of the workers. In addition, we like to be able to login between the workers.

We have chosen a very simple setup while relying on ssh tunnel.

To simplify the setup of this we have developed a command cms host that gathers and scatters keys onto all machines, as well as sets up the tunnels.

It is essential that that the key on the laptop must not be password less. This is also valid for any machine that is directly added to the network such as in the mesh notwork.

To avoid password less keys we recommend you to use ssh-add or ssh-keychain which will ask you for one.

The manual page for cms host is provided in the Manual Pages section.

Step 1. On the manager create ssh keys for each of the workers.

(ENV3) pi@managerpi:~ $ cms host key create red00[1-3]

Step 2. On the manager gather the worker, manager, and your laptop public ssh keys into a file.

(ENV3) pi@managerpi:~ $ cms host key gather red00[1-3],you@yourlaptop.local keys.txt

Step 3. On the manager scatter the public keys to all the workers and manager ~/.ssh/authorized_hosts file

(ENV3) pi@managerpi:~ $ cms host key scatter red00[1-3],localhost keys.txt

Step 4. Remove undeeded keys.txt file

(ENV3) pi@managerpi:~ $ rm keys.txt

Step 5. Verify SSH reachability from worker to manager and worker to worker.

(ENV3) pi@managerpi:~ $ ssh red001
pi@red001:~ $ ssh managerpi.local

BUG: The workers still currently still need to use .local after names. This will be resolved by the inventory create update.

(ENV3) pi@managerpi:~ $ exit
pi@red001:~ $ ssh red002.local
pi@red002:~ $ exit
pi@red001:~ $ exit

Step 6. (For Bridge setup) Create SSH tunnels on the manager to enable ssh acces from your laptop to the workers

For now we manually install autossh, to test the new cms host tunnel program. Later we add it to the main manager setup script.

(ENV3) pi@managerpi:~ $ yes y | sudo apt install autossh
(ENV3) pi@managerpi:~ $ cms host tunnel create red00[1-3]

Step 7. (For Bridge setup) Copy the specified command output to your ~/.ssh/config file on your laptop

host tunnel create red00[1-3]

Using wlan0 IP = 192.168.1.17
Using cluster hostname = managerpi

Tunnels created.

Please place the following in your remote machine's (i.e. laptop)
`~/.ssh/config` file to alias simple ssh access (i.e. `ssh red001`).

# ----------------------------------------------------------------------
# copy to ~/.ssh/config on remote host (i.e laptop)
# ----------------------------------------------------------------------

Host red001
     HostName managerpi.local
     User pi
     Port 8001

Host red002
     HostName managerpi.local
     User pi
     Port 8002

Host red003
     HostName managerpi.local
     User pi
     Port 8003

Note: We will in future provide an addition to the command so you can remove and add them directly from the commandline

cms host tunnel config create red00[1-3]
cms host tunnel config delete red00[1-3]

Step 8. (For Bridge setup) Verify SSH reachability from the laptop to workers

you@yourlaptop:~ $ ssh red001

Manual Pages

Manual Page for the burn command

Note to execute the command on the commandline you have to type in cms burn and not jsut burn.

  burn firmware check
  burn firmware update
  burn install
  burn load --device=DEVICE
  burn format --device=DEVICE
  burn imager [TAG...]
  burn mount [--device=DEVICE] [--os=OS]
  burn unmount [--device=DEVICE] [--os=OS]
  burn network list [--ip=IP] [--used]
  burn network
  burn info [--device=DEVICE]
  burn image versions [--refresh] [--yaml]
  burn image ls
  burn image delete [--image=IMAGE]
  burn image get [--url=URL] [TAG...]
  burn backup [--device=DEVICE] [--to=DESTINATION]
  burn copy [--device=DEVICE] [--from=DESTINATION]
  burn shrink [--image=IMAGE]
  burn create [--image=IMAGE]
              [--device=DEVICE]
              [--hostname=HOSTNAME]
              [--ip=IP]
              [--sshkey=KEY]
              [--blocksize=BLOCKSIZE]
              [--dryrun]
              [--passwd=PASSWD]
              [--ssid=SSID]
              [--wifipassword=PSK]
              [--format]
              [--tag=TAG]
              [--inventory=INVENTORY]
              [--name=NAME]
  burn sdcard [TAG...] [--device=DEVICE] [--dryrun]
  burn set [--hostname=HOSTNAME]
           [--ip=IP]
           [--key=KEY]
  burn enable ssh
  burn wifi --ssid=SSID [--passwd=PASSWD] [--country=COUNTRY]
  burn check [--device=DEVICE]
  burn mac --hostname=HOSTNAME

Options:
  -h --help              Show this screen.
  --version              Show version.
  --image=IMAGE          The image filename,
                         e.g. 2019-09-26-raspbian-buster.img
  --device=DEVICE        The device, e.g. /dev/sdX
  --hostname=HOSTNAME    The hostname
  --ip=IP                The IP address
  --key=KEY              The name of the SSH key file
  --blocksize=BLOCKSIZE  The blocksise to burn [default: 4M]

Arguments:
    TAG                  Keyword tags to identify an image
                         [default: latest]
Files:
  This is not fully thought through and needs to be documented
  ~/.cloudmesh/images
    Location where the images will be stored for reuse

Description:
    cms burn create --inventory=INVENTORY --device=DEVICE --name=NAME

        Will refer to a specified cloudmesh inventory file (see cms help inventory).
        Will search the configurations for NAME inside of INVENTORY and will burn
        to DEVICE. Supports parameter expansion.

    cms burn create --passwd=PASSWD

         if the passwd flag is added the default password is
         queried from the commandline and added to all SDCards

         if the flag is omitted login via the password is
         disabled and only login via the sshkey is allowed

  Network

    cms burn network list

        Lists the ip addresses that are on the same network

         +------------+---------------+----------+-----------+
         | Name       | IP            | Status   | Latency   |
         |------------+---------------+----------+-----------|
         | Router     | 192.168.1.1   | up       | 0.0092s   |
         | iPhone     | 192.168.1.4   | up       | 0.061s    |
         | red01      | 192.168.1.46  | up       | 0.0077s   |
         | laptop     | 192.168.1.78  | up       | 0.058s    |
         | unkown     | 192.168.1.126 | up       | 0.14s     |
         | red03      | 192.168.1.158 | up       | 0.0037s   |
         | red02      | 192.168.1.199 | up       | 0.0046s   |
         | red        | 192.168.1.249 | up       | 0.00021s  |
         +------------+----------------+----------+-----------+

    cms burn network list [--used]

        Lists the used ip addresses as a comma separated parameter
        list

           192.168.50.1,192.168.50.4,...

    cms burn network address

        Lists the own network address

         +---------+----------------+----------------+
         | Label   | Local          | Broadcast      |
         |---------+----------------+----------------|
         | wlan0   | 192.168.1.12   | 192.168.1.255  |
         +---------+----------------+----------------+

    cms burn firmware check

        checks if the firmware on the Pi is up to date

    cms burn firmware update

        checks and updates the firmware on the Pi

    cms burn install

        installs a program to shrink img files. THis is
        useful, after you created a backup to make the
        backup smaller and allow faster burning in case of
        recovery

    cms burn load --device=DEVICE

        loads the sdcard into the USB drive. Thi sis similar to
        loading a cdrom drive. It s the opposite to eject

    cms burn format --device=DEVICE

        formats the SDCard in the specified device. Be
        careful it is the correct device.  cms burn info
        will help you to identifying it

    cms burn mount [--device=DEVICE] [--os=OS]

        mounts the file systems available on the SDCard

    cms burn unmount [--device=DEVICE] [--os=OS]

        unmounts the mounted file systems from the SDCard

    cms burn info [--device=DEVICE]

        provides useful information about the SDCard

    cms burn image versions [--refresh] [--yaml]

        The images that you like to burn onto your SDCard
        can be cached locally with the image command.  The
        available images for the PI can be found when
        using the --refresh option. If you do not specify
        it it reads a copy of the image list from our
        cache

    cms burn image ls

        Lists all downloaded images in our cache. You can
        download them with the cms burn image get command

    cms burn image delete [--image=IMAGE]

        deletes the specified image. The name can be found
        with the image ls command

    cms burn image get [--url=URL] [TAG...]

        downloads a specific image or the latest
        image. The tag are a number of words separated by
        a space that must occur in the tag that you find
        in the versions command

    cms burn backup [--device=DEVICE] [--to=DESTINATION]

        backs up a SDCard to the given location

    cms burn copy [--device=DEVICE] [--from=DESTINATION]

        copies the file form the destination on the SDCard
        this is the same as the SDCard command. we will in
        future remove one

    cms burn shrink [--image=IMAGE]

        shrinks the size of a backup or image file that
        is on your local file system. It can only be used
        for .img files

    cms burn create [--image=IMAGE]
                    [--device=DEVICE]
                    [--hostname=HOSTNAME]
                    [--ip=IP]
                    [--sshkey=KEY]
                    [--blocksize=BLOCKSIZE]
                    [--dryrun]
                    [--passwd=PASSWD]
                    [--ssid=SSID]
                    [--wifipassword=PSK]
                    [--format]

        This command  not only can format the SDCard, but
        also initializes it with specific values

    cms burn sdcard [TAG...] [--device=DEVICE] [--dryrun]

        this burns the sd card, see also copy and create

    cms burn set [--hostname=HOSTNAME]
                 [--ip=IP]
                 [--key=KEY]
                 [--mount=MOUNTPOINT]

        this sets specific values on the sdcard after it
        has ben created with the create, copy or sdcard
        command

        a --ssh is missing from this command

    cms burn enable ssh [--mount=MOUNTPOINT]

        this enables the ssh server once it is booted

    cms burn wifi --ssid=SSID [--passwd=PASSWD] [--country=COUNTRY]

        this sets the wifi ssid and password after the card
        is created, copied, or the sdcard is used.

        The option country option expects an ISO 3166-1
        two digit country code. The default is "US" and
        the option not required if suitable. See
        https://en.wikipedia.org/wiki/ISO_3166-1 for other
        countries.

    cms burn check [--device=DEVICE]

        this command lists the parameters that were set
        with the set or create command

Examples: ( \ is not shown)

   > cms burn create --image=2019-09-26-raspbian-buster-lite
   >                 --device=/dev/mmcblk0
   >                 --hostname=red[5-7]
   >                 --ip=192.168.1.[5-7]
   >                 --sshkey=id_rsa

   > cms burn image get latest

   > cms burn image get https://downloads.raspberrypi.org/
   >   raspbian_lite/images/
   >   raspbian_lite-2018-10-11/2018-10-09-raspbian-stretch-lite.zip

   > cms burn image delete 2019-09-26-raspbian-buster-lite

Manual Page for the bridge command

Note to execute the command on the commandline you have to type in cms bridge and not jsut bridge.


Options:
    --interface=INTERFACE  The interface name [default: eth1]
                           You can also specify wlan0 if you want
                           to bridge through WIFI on the manager
                           eth0 requires a USB to WIFI adapter

   --ip=IP  The ip address to assign on the eth0 interface,
            ie. the listening interface [default: 10.1.1.1]

  --dns=NAMESERVER  The ip address of a nameserver to set statically
           For example, --dns=8.8.8.8,8.8.4.4 will use google
           nameservers

Description:

  Command used to set up a bride so that all nodes route the traffic
  trough the manager PI.

  bridge create [--interface=INTERFACE] [--ip=IP] [--dns=NAMESERVER]
      creates the bridge on the current device.
      A reboot is required.

Manual Page for the host command

Note to execute the command on the commandline you have to type in cms host and not jsut host.

    host scp NAMES SOURCE DESTINATION [--dryrun]
    host ssh NAMES COMMAND [--dryrun] [--output=FORMAT]
    host config NAMES [IPS] [--user=USER] [--key=PUBLIC]
    host check NAMES [--user=USER] [--key=PUBLIC]
    host key create NAMES [--user=USER] [--dryrun] [--output=FORMAT]
    host key list NAMES [--output=FORMAT]
    host key gather NAMES [--authorized_keys] [FILE]
    host key scatter NAMES FILE
    host tunnel create NAMES [--port=PORT]
    host mac NAMES [--eth] [--wlan] [--output=FORMAT]

This command does some useful things.

Arguments:
    FILE   a file name

Options:
    --dryrun   shows what would be done but does not execute
    --output=FORMAT  the format of the output
    --port=PORT starting local port for tunnel assignment

Description:

    host scp NAMES SOURCE DESTINATION

      TBD

    host ssh NAMES COMMAND

      runs the command on all specified hosts
      Example:
           ssh red[01-10] "uname -a"

    host key create NAMES
      create a ~/.ssh/id_rsa and id_rsa.pub on all hosts specified
      Example:
          ssh key create "red[01-10]"

    host key list NAMES

      list all id_rsa.pub keys from all hosts specifed
       Example:
           ssh key list red[01-10]

    host key gather HOSTS FILE

      gathers all keys from file FILE including the one from localhost.

          ssh key gather "red[01-10]" keys.txt

    host key scatter HOSTS FILE

      copies all keys from file FILE to authorized_keys on all hosts,
      but also makes sure that the users ~/.ssh/id_rsa.pub key is in
      the file.

      1) adds ~/.id_rsa.pub to the FILE only if its not already in it
      2) removes all duplicated keys

      Example:
          ssh key scatter "red[01-10]"

    host key scp NAMES FILE

      copies all keys from file FILE to authorized_keys on all hosts
      but also makes sure that the users ~/.ssh/id_rsa.pub key is in
      the file and removes duplicates, e.g. it calls fix before upload

      Example:
          ssh key list red[01-10] > pubkeys.txt
          ssh key scp red[01-10] pubkeys.txt

    host config NAMES IPS [--user=USER] [--key=PUBLIC]

      generates an ssh config file tempalte that can be added to your
      .ssh/config file

      Example:
          cms host config "red,red[01-03]" "198.168.1.[1-4]" --user=pi

    host check NAMES [--user=USER] [--key=PUBLIC]

      This command is used to test if you can login to the specified
      hosts. It executes the hostname command and compares it.
      It provides a table  with a sucess column

      cms host check "red,red[01-03]"

          +-------+---------+--------+
          | host  | success | stdout |
          +-------+---------+--------+
          | red   | True    | red    |
          | red01 | True    | red01  |
          | red02 | True    | red02  |
          | red03 | True    | red03  |
          +-------+---------+--------+

    host tunnel create NAMES [--port=PORT]

      This command is used to create a persistent local port
      forward on the host to permit ssh tunnelling from the wlan to
      the physical network (eth). This registers an autossh service in
      systemd with the defualt port starting at 8001.

      Example:
          cms host tunnel create red00[1-3]

    host mac NAMES

      returns the list of mac addresses of the named pis.

Manual Page for the pi command

Note to execute the command on the commandline you have to type in cms pi and not jsut pi.

Note: Please note that the command hadoop, spark, and k3 are experimental and do not yet work. In fact the hadoop and spark deployment are not fullfilling our standard and should not be used. They will be put into a different command soon so they are not confusing the used in this README. The command is likely to be called pidev. Once the command is graduated it will be moved into the main command pi.

There is some very usefull aditional information about how to use the LED and temperature monitoring programs at

  pi led reset [NAMES]
  pi led (red|green) VALUE
  pi led (red|green) VALUE NAMES [--user=USER]
  pi led list NAMES [--user=USER]
  pi led blink (red|green) NAMES [--user=USER] [--rate=SECONDS]
  pi led sequence (red|green) NAMES [--user=USER] [--rate=SECONDS]
  pi temp NAMES [--rate=RATE] [--user=USER] [--output=FORMAT]
  pi free NAMES [--rate=RATE] [--user=USER] [--output=FORMAT]
  pi load NAMES [--rate=RATE] [--user=USER] [--output=FORMAT]
  pi script list SERVICE [--details]
  pi script list SERVICE NAMES
  pi script list
  pi wifi SSID [PASSWORD] [--dryrun]

This command does some useful things.

Arguments:
    FILE   a file name

Options:
    -f      specify the file


Description:

  This command switches on and off the LEDs of the specified
  PIs. If the hostname is omitted. It is assumed that the
  code is executed on a PI and its LED are set. To list the
  PIs LED status you can use the list command

  Examples:

      cms pi led list  "red,red[01-03]"

          lists the LED status of the given hosts

      cms pi led red off  "red,red[01-03]"

          switches off the led of the given PIs

      cms pi led red on  "red,red[01-03]"

          switches on the led of the given PIs

      cms pi led red blink  "red,red[01-03]"

          switches on and off the led of the given PIs

      cms pi led red sequence  "red,red[01-03]"

          goes in sequential order and switches on and off
          the led of the given PIs

FAQ and Hints

Here, we provide some usefule FAQs and hints.

Can I use the LEDs on the PI Motherboard?

Typically this LED is used to communicate some system related information. However cms pi can controll it to switch status on and off. This is helpful if you like to showcase a particular state in the PI. Please look at the manual page. An esample is

$ cms pi led red off HOSTNAME

that when executed on the PI (on which you also must have cms installed you switch the red LED off. For more options see the manual page

How can I use pycharm, to edit files or access files in general from my Laptop on the PI?

This is easily possible with the help of SSHFS. To install it we refer you to See also: https://github.com/libfuse/sshfs SSHFS: add manager to .ssh/config onlocal machine

Let us assume you like to edit fles on a PI that you named red

Please craete a `./.ssh/config file that containes the following:

 Host red
      HostName xxx.xxx.xxx.xxx
      User pi
      IdentityFile ~/.ssh/id_rsa.pub

Now let us create a directory in which we mount the remote PI directories

mkdir manager
sshfs manager: manager -o auto_cache

How can I enhance the get script?

Instead of using the link

please use

This allows us to test also modifications to the get script before we push them to the official community repository.

You can create a pull request at

Can I use a Mesh Network for the setup?

This section is still under development.

In case you have a Mesh Network, the setup can typically be even more simplifies as we can attach the unmanaged router directly to a Mesh node via a network cable. IN that case the node is directly connected to the internet and uses the DHCP feature from the Mesh router (see Figure 2).

Figure 2: Networking with Mesh network

You will not need the bridge command to setup the network.

Can I use cms burn on Linux?

Not everything is supported.

To download the latest Raspberry Pi OS Lite image use

cms burn image get latest-lite

To see what SDCard writers you have attached, you can use the command

cms burn info

It will issue a probe of USB devices and see if SDCards can be found.

Identify the /dev/sdX, where X is a letter such as b,c,d, … It will likely never be a.

sudo apt-get install pv cms burn sdcard –dev=/dev/sdX cms burn mount –device=/dev/sdX cms burn enable ssh cms burn unmount

Take the SDCard into the PI and set it up there. as documented.

What packages do I need to run the info command on macOS

brew install libusb
nrew install pv

Access to ext4: For the more advanced features of burn you will need full write access to the ext4 partition on your SDCard that is created when you burn it. Unfortunately the tools that used t be freely available see no longerto work properly, so you could use extFS for Mac by Paragon Software which does cost $40 for a license.

Are there any unit tests?

As cms burn may delete format, delete, and remove files during unit testing users are supposed to first review the tests before running them. Please look at the source and see if you can run a test.

we have the following tests:

  • pytest -v --capture=no tests/test_01_image.py
    • This test removes files forom ~/.cloudmesh/cmburn/images
    • See also: test_01_image.py

Using Pi Imager to setup a Manager Pi with headless access

This FAQ will provide step by step instructions for burning and accessing a headless manager pi. We will include instructions for either wifi access to the pi or local ethernet connection.

If you have restricted WIFI that requires you to register you devices MAC address via a web browser (think hotel wifi access page), you might not be able to continue with a headless setup.

This FAQ references instructions from <https://www.raspberrypi. org/documentation/remote-access/ssh/> and <https://www.raspberrypi. org/documentation/configuration/wireless/headless.md>

Step 1.

Download and install the Pi Imager software from raspberrypi.org <https://www. raspberrypi.org/software/>.

Step 2.

Launch the Pi Imager software, insert an SD card reader and SD card into your laptop.

Step 3.

Choose the OS in the Pi Imager interface. We will use **Raspberry Pi OS (32-BIT) with the Raspberry Pi desktop.

Step 4.

Choose the SD card in the Pi Imager interface. If you do not see an SD card and a reader is plugged into your laptop, remove and re-insert the sd card reader.

Step 5.

Push the ‘Write’ button and confirm the settings to burn the OS to your SD card. You may need to put in the SUDO password to burn the card. This will take some time. USB 3.0 devices are faster than USB 2.0. Make sure your cable is USB 3.0 as well.

Step 6.

Mount the SD card. This can be accomplished easily in Linux by unplugging and replugging in the device. On Pi and Linux you should see the boot partition at /media/$USER/boot (where user is you username) and on MacOS at /Volumes/boot. I will use Linux for the example. Substitute as required for MacOS.

Step 7.

Enable SSH access to the SD card. At the command prompt

you@yourlaptop:~ $ cd /media/$USER/boot
you@yourlaptop:/media/$USER/boot $ touch ssh

This creates and empty file named ssh in the boot partition. On the first boot, this enables the SSH service, and then empty ssh file will be automatically deleted.

Step 8.

If only have wireless access to your Pi. You need to setup the wireless configuration.

If you have restricted WIFI that requires you to register you devices MAC address via a web browser (think hotel wifi access page), you might not be able to continue with a headless setup.

Otherwise you can continue without this step if you have ethernet access between your laptop and pi (either via switch or direct cable). After plugging into a shared switch with the Pi, or directly to it, you will need to make sure you see a link local address on your ethernet port on your laptop. It should look something like 169.254.X.X. If you do not see this investigate how to setup a link local ip on your OS.

you@yourlaptop:/media/$USER/boot $ nano /media/$USER/boot/wpa_supplicant.conf

#Insert this into the file and save (CTRL-X, Y, Enter).

ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev
update_config=1
country=<Insert 2 letter ISO 3166-1 country code here e.g. US>

network={
 ssid="<Name of your wireless LAN>"
 psk="<Password for your wireless LAN>"
}

Step 9.

Unmount and eject the SD card.

you@yourlaptop:~ $ sudo umount /media/$USER/boot
you@yourlaptop:~ $ sudo umount /media/$USER/rootfs

Step 10.

Boot a pi with the SD card. Wait a few minutes and try to access it via SSH. Use the Raspi OS default username “pi” and “raspberry”.

you@yourlaptop:~ $ ssh pi@raspberrypi.local

Step 11.

Change the password.

pi@raspberrypi:~ $ passwd

Step 12.

Change the hostname to managerpi.

pi@raspberrypi:~ $ sudo raspi-config
<1. System Options>
<S4 Hostname>
enter
managerpi
<Finish>
Would you like to reboot?
<Yes>

Step 13.

Wait a minute or two and reconnect. Now using the new hostname.

you@yourlaptop:~ $ ssh pi@managerpi.local

Step 14.

You are all done. You are ready to proceed with Quickstart for Bridged WiFi. You will now witness the magic of how cms burn automates this process for you.

pi@managerpi:~ $

Single Card Burning

Step 0. Ensure the SD card is inserted.

We can run cms burn info again as we did above to verify our SD card is connected.

Step 1. Burning the SD Card

Choose a hostname for your card. We will use red001 with ip 10.1.1.2. The IP address 10.1.1.1 is reserved for the burner pi (ie. managerpi).

Note we are using the subnet 10.1.1.0/24 in this guide. We currently recommend you do the same, otherwise the WiFi bridge will not configure correctly. We will change this in the future to support other Private IP Ranges

!! WARNING VERIFY THE DEVICE IS CORRECT. REFER TO CMS BURN !!

(ENV3) pi@managerpi:~ $ cms burn create --hostname=red001 --ip=10.1.1.2 --device=/dev/sda --tag=latest-lite

Wait for the card to burn. Once the process is complete, it is safe to remove the SD card.

We can now proceed to the bridge setup

How to update firmware?

To update the firmware reference the raspi documentation

Or follow the simple instructions below.

pi@managerpi:~ $ sudo apt update
pi@managerpi:~ $sudo apt full-upgrade
pi@managerpi:~ $sudo reboot
pi@managerpi:~ $sudo rpi-eeprom-update -a
pi@managerpi:~ $sudo reboot

How to burn a cluster using Linux

This will setup the same cluster seen in Quickstart for Bridged WiFi using only a Linux machine. Pi imager and a manual manager pi setup process is not required using this method.

Prerequisites

  • We recommend Python 3.8.2 Python or newer.
  • We recommend pip version 21.0.0 or newer
  • You have a private and public ssh key named ~/.ssh/id_rsa and ~/. ssh/id_rsa.pub

Install Cloudmesh

Create a Python virtual environment ENV3 in which to install cloudmesh. This will keep cloudmesh and its dependecies seperate from your default environment.

Always make sure to source this environment when working with cloudmesh.

you@yourlaptop:~ $ python -m venv ~/ENV3
you@yourlaptop:~ $ source ~/ENV3/bin/activate 
you@yourlaptop:~ $ mkdir cm
you@yourlaptop:~ $ cd cm
you@yourlaptop:~ $ pip install cloudmesh-installer
you@yourlaptop:~ $ cloudmesh-installer get pi

Create a Manager Pi

Step 1. Get the latest RaspiOS-full image

you@yourlaptop:~ $ cms burn image get latest-full

Step 1. Insert and SD card to your laptop and identify the sd card device name using:

you@yourlaptop:~ $ cms burn info

Step 2. Burn the manager pi.

!! WARNING VERIFY THE DEVICE IS CORRECT. REFER TO CMS BURN !!

you@yourlaptop:~ $ cms burn create --hostname=managerpi --tag=latest-full--device=/dev/sdX --ssid=your_wifi --wifipassword=your_password

Create the workers

Step 1. Download the latest RaspiOS-lite image

cms burn image get latest-lite

Step 2. Burn the workers

!! WARNING VERIFY THE DEVICE IS CORRECT. REFER TO CMS BURN !!

cms burn create --hostname=red00[1-4] --ip=10.1.1.[2-5] --device=/dev/sdX --tag=latest-lite

Step 3. Turn off the cluster, insert sd cards, turn on cluster, and connect to the manager pi.

you@yourlaptop:~ $ ssh pi@mangerpi.local

Step 4. Update and install cloudmesh on your manager pi

Update pip. The simple curl command below will generate an ssh-key, update your system, and install cloudmesh.

pi@managerpi:~ $ pip install pip -U
pi@managerpi:~ $ curl -Ls http://cloudmesh.github.io/get/pi | sh -                
pi@managerpi:~ $ sudo reboot

Step 4. Enable the bridge on the mangerpi.

See section Connecting Pis to the Internet via Bridge

Step 5. Generate and distribute SSH keys

See section Set up of the SSH keys and SSH tunnel

Step 6. Enjoy your Pi cluster :)

Alternatives

There are several alternatives to make the setup easier:

  • Using Ansible after you have created the SDCards via PIImager. THis however requires still the discovery of the hosts on the network and additional steps.
  • PiBakery can burn cards while allowing startup scripts and naming hosts. Although the GUI is nice it is also a limiting factor as each card shoudl have a different hostname
  • Using DHCP to get ip addresses automatically. THis is a solution we also used but do not present here
  • PXE or network booting whch allsows you to boot from the network. For larger PI clusters this requires multiple Servers so that the network is not everwhelmed. Starting the cluster takes much longer.

What is the status of the implementation?

FeaturePIUbuntuMacWindows
image versions+++
image ls+++
image delete+++
image get+++
info+++
network++
backup++-
copy++-
shrink install++
shrink++
sdcard+++
mount+++
unmount+++
enable ssh+++
wifi+++
set++TODO1
createTODOTODOTODO
check+++
format+++
firmwarea +NANANA
  • for macOS, only the image commands have unit tests
  • firmware does not have a unit test

empty = not yet implemented

    • = verified throug unit test either by ANthony or Gregor
    • broken

  • TODO1 = todo for boot fs, rootfs not supported

  • 2 = change and add –ssd so its uniform 1 = get needs to use the image versions refresh cache

How can I contribute Contributing

The code uses a variety of cloudmesh components. This mainly includes

Additional cloudmesh components ar used. For example:

4 - Fortan

In case you like to experiment with FORTRAN, you can install and use it.

Learning Objective

Python is in scientific computing still used. It is easy to set up on a Pi so you can experiment with it.

  • Set op Fortan
  • Run it on your PI

Topics Covered

You may find still that many scientific programs are written in fortran. For some smaller fortran programs it is even possible to run them on a Raspberry pi.

Installation

Naturally you will need to install a fortran compiler, which you can do with

pi$ sudo apt-get install gfortran

Example

To test it out store the following program into hello.f90

program hello
    print *, "Hello World!"
end program hello

Now you can compile it with

pi$ gfortran -o hello hello.f90

Execute it with

pi$ hello

5 - Kubernetes

Links related to running Kubernetes on a Pi cluster.

Learning Objectives

  • Get informed what others do

Topics covered

TBD

Complete to this format:

fedora

x86 via docker

Raspbian

Ubuntu

RancherOS

k8s

k3s

Hyperoid, k3s

TuringPI

k3sup

microk8

Medium.com

Requires fee, if you read several articles (I have not read them)

Services

Azure SQL Edge

6 - Motherboard LED

In some cases it it useful to visually display information about the state or programs on your cluster. The LEDs on the board can be used for that.

Learning Objective

Find out how to use the LEDs on the motherboard.

  • Set op Fortan
  • Run it on your PI

Topics Covered

Using Cloudmesh to Control the LEDs

The most convenient way to control the motherboard LEDs is via Cloudmesh. It includes a special command that can even be called from a remote Pi using ssh once you hve set up the cluster with cloudmesh.

This command switches on and off the LEDs of the specified PIs. If the hostname is omitted. It is assumed that the code is executed on a PI and its LED are set.

The specialty of this program is that it not only can query the current state, but also allows you to set multiple LEDs on different motherboards at the same time with a convenient parameterized syntax.

Examples

We present a number of examples on how to use this command

cms pi led list  "red,red[01-03]"

lists the LED status of the given hosts

cms pi led red off  "red,red[01-03]"

switches off the led of the given PIs

cms pi led red on  "red,red[01-03]"

switches on the led of the given PIs

cms pi led red blink  "red,red[01-03]"

switches on and off the led of the given PIs

cms pi led red sequence  "red,red[01-03]"

goes in sequential order and switches on and off the led of the given PIs

Syntax

The command syntax is

cms pi led reset [NAMES]
cms pi led (red|green) VALUE
cms pi led (red|green) VALUE NAMES [--user=USER]
cmspi led list NAMES [--user=USER]

Using Motherboard LEDs from Shell Scripts

The Raspberry pi contains an LED that can also be used to provide us with some information as to the status of the PI. It is usually used for reporting the power status.

The green LED can be made blinking as follows in root

echo 1 > /sys/class/leds/led0/brightness
echo 0 > /sys/class/leds/led0/brightness

Controlling the Motheboard LEDs remotely via ssh

Naturally this ac be done via a remote command if your ssh keys are uploaded and your originating computer is added to the authorized_keys. Now you can can control them via ssh

ssh pi@red03 "echo 1 > led; sudo cp led /sys/class/leds/led0/brightness"
ssh pi@red03 "echo 0 > led; sudo cp led /sys/class/leds/led0/brightness"

This is extremely useful as it allows us to check if we the OS is available and we can access the PI.

One strategy is to for example switch the light of, once it is booted, so we can see which board may be in trouble.

7 - Run at Boot

To run programs at boot time you have several options. learn about them here.

Learning Objective

In case you need to run a program at boottime you have several option we discuss here.

Topics Covered

Run Commands at Boot time

In many cases we need to provide configurations and programs that run at boot time. A number of different methods exist to run commands and programs at boot time.

We will be focusing here only a few of them

rc.local

On your Pi you will find under /etc/rc.local a file in which you can list programs that are started up at boot time. The programs should success fully run and exit with the status 0, and they must not continuously run in which case they need to be started in background.

To make sure you do not forget it, simply add the following line at the end of your program

exit 0

indicating that the start was successful. Programs in rc.local must use the absolute file path.

Crontab

Crontab is a service the schedules jobs that can run at various times repeatedly. For example we can use crontab to run commands every hour, every day, every half hour or other time intervals or at reboot.

To use crontab follow these steps

  1. Open a terminal and enter the command

    $ crontab -e

    If you are doing this for the first time, you will be asked to chose an editor. Please, choose your favorite editor

  2. To run the program at boot time, add the following line to the at the end of the file

     @reboot <command>

Let us look at an example and assume we have test.py program in your home directory at /home/pi/test.py. Once you add it to crontab with

 @reboot python /home/pi/test.py

it will be run at boot time

It is important to provide the absolute path to the file. In case your file produces output you need to redirect it into a file

  @reboot python /home/pi/test.py > /home/pi/test.log
  • When the raspberry pi reboots, the program will run automatically.

References

A good introduction to the various methods is provided at

For more information on crontab see for example: