How Pantacor Hub and Pantavisor work together

Pantacor Hub and Pantavisor can sometimes be a difficult paradigm to understand. In  some ways, it completely changes how we relate to and interact with the firmware and software on embedded Linux devices.

When you build something on an embedded device, for example an IoT project or a home automation project on your Raspberry Pi, the first thing you might do is flash your device with a Linux distribution. After that you install the necessary packages and configure all of them via ssh. If you run into an issue, you may have to start from the beginning and do it all over again. To automate that process a little bit, you may consider creating a shell script that handles all of the manual configuration and installation.

This is manageable with one or two devices, but what happens if you need to update the configuration for a fleet of devices? You could make your script a lot more sophisticated and there are certainly many tools for that. But what happens if your devices are running very little memory? That’s when your plans can quickly fall apart.

Portable and repeatable device updates

What we all wish for are devices and configuration to be like Docker images and Docker containers that don’t need constant updates and that can be configured on the device once. In our case, the device is flashed and then claimed on Pantacor Hub (or cloned to your laptop) where you can post revisions that are deployed on the device. Pantacor Hub can even set a device to be the leader of a pack (or fleet), where the whole pack automatically accepts revisions from the leader all at once.

But before we get into that let’s understand the terminology that we are using and includes: devices, revisions, platforms, and how Pantacor Hub and Pantavisor fits into it.

What is Pantacor Hub?

Pantacor Hub offers cloud-controlled firmware and software management for all kinds of Linux-based connected devices. In addition to this, Pantacor Hub is a community ecosystem for device makers, operators, and technology enthusiasts to gather around and share their work and also revisions of their work.

But before you can use Pantacor Hub, you will need to first install Pantavisor on your devices.

What is Pantavisor?

Pantavisor is the Linux device init system that turns all the runtime into a set of containerized micro-functions. Through Pantavisor, devices become software-defined infrastructure with Linux container technology. It also allows all Pantavisor-enabled devices to automatically connect to a Pantacor Hub instance where it can be remotely management from.

With these two technologies, you can manage your devices and their software in a way that is similar (similar but not the same) to how you manage applications with Docker containers.

But instead of having a container running on the device, the device runs the PLATFORM directly on metal, allowing you to have versions of the device. This device state version is called a REVISION that is kept in Pantacor Hub and where you will have the ability to return to a previous revision or state. This means that your device is completely fault-tolerant. If you deploy a revision that can’t run correctly on the device, it reverts to the last revision that worked correctly. You can be ensured that you will never lose or brick your device if you configure something incorrectly or if the software has any kind of problem.

How the ecosystem works

The ecosystem looks similar to how you view containers on Docker hub, but instead of containers, you see devices that have been connected by Pantavisor.

This is how a device is displayed in Pantacor Hub.

A device shown in Pantacor Hub is a physical device. In this example, a Raspberry Pi 3 b+ with several PLATFORMS/APPS running is displayed. The PLATFORMS/APPS are built from a Docker container, however inside of the device there is no Docker runtime.

In this example, the device is running the following:

  • cloudflare: Platform installed by to manage the DNS configuration and sets the DNS filters for your WIFI hotspot.
  • awconnect: Manages the network and the wifi connections.
  • pv-avahi: Exposes an mDNS configuration that discovers any Pantacor Hub-enabled device on the network using the PVR CLI or the mobile application.
  • pvr-sdk: Manages some of the functionalities of the device like the SSH connection, the ability to follow devices, read user metadata and so much more.

You can see how a device is composed of several platforms based on Docker containers. But remember, there isn’t an actual Docker container running on the device. They are instead LXC containers.

The device revision is described as a JSON file converted to a file system after you clone the device.

Let me explain with a visual example using the same device.

We call this JSON device specification a revision state.json

As you can see, the STATE is a normalized JSON format with the folder structure of the device, where any .json file inside that structure is part of state.json. Any other file format represented by the sha256 of that file is saved in Pantacor Hub as objects (which is our storage in the cloud)

When you run  pvr clone URL_OF_DEVICE (just like a git clone), you get the same structure as in the state.json but instead the files represented as a sha256 are downloaded.

The result is a folder like this.

Every platform lives in its own folder and all the configuration files live inside of the _config/${PLATFORM} folder

If you want to dive deep in all the available endpoints you can read the API reference here in the documentation or the swagger documentation here