Rockface Documentation

Appearance

Rockface Tutorial ​

In this tutorial you'll learn the basics of how to interact with your hardware that's installed in Rockface. In order to complete this tutorial, you will need to have signed-up, and we need to have completed the installation of your hardware.

Rigs and Tools ​

To get started, there are two main concepts within Rockface that you'll need to be familiar with: tools and rigs.

Tools ​

A tool can interact with or monitor your hardware in a fully automated way.

Tools are like the equipment you might find on an electronics workbench, except they're entirely remotely controllable, and cover a broader set of applications. Here are two examples to give you the general idea:

  1. A power supply tool delivers power to your hardware, just like a bench power supply. It can be turned on and off remotely, and (depending on the capabilities of the particular supply fitted to your hardware) can do things like reports its output current.

  2. A USB serial tool acts as a USB host to your hardware. It can communicate with any USB client that implements a standard USB serial emulation interface, like CDC-ACM.

In short, Rockface tools encompass all of the interfaces that you and your code will need to be able to interact with your hardware remotely.

Rigs ​

A rig is made up of your hardware and a set of tools. You can see the list of rigs associated with your account on the dashboard — each one has a unique name that your software can use to refer to it.

Your rig will likely have a few tools. For example, it might have a a couple of power supplies, a logic analyser, and an SWD programmer/debugger.

Set up your development environment ​

Rockface provides a python library, called rockface, for interacting with your rigs and their tools. You'll need to install this package to use it. Run the following command to install it with the python package manager pip:

sh
pip install rockface
Versioning and Rockface

The Rockface python library uses semantic versioning to communicate compatibility. We will not introduce backward-incompatible changes without incrementing the major version number.

When you start integrating Rockface into your software, you'll almost certainly want to pin to at least the major version number in your project's dependencies (e.g. in setup.cfg or pyproject.toml).

Get your API key ​

Your code will need to authenticate itself with the Rockface API using an "API key". You can generate an API key using the "API keys" page on the dashboard. This API key allows control of your rig, so keep it a secret.

Providing the API key through an environment variable

There are two ways you can provide an API key to the Rockface python library:

  1. As an argument when you create a Rig object.
  2. Through the environment variable ROCKFACE_API_KEY. In this case you don't need to provide an API key when you create a Rig object.

Take control of your rig ​

Let's start with a small example that just simply 'finds' the rig, and then we'll move on to explore what you can do with it.

Open your favourite text editor or IDE, and create a python file with the following content:

py
#!/usr/bin/env python3
from rockface import Rig

# You got this from the dashboard!
API_KEY="replace this with your API key"

with Rig.find_by_name("my-rig-name", api_key=API_KEY) as rig:
    print(f"Lock acquired for rig with name '{rig.name}'")

You will need to change the value of API_KEY to be your API key, and change the first argument provided to Rig.find_by_name to be the rig name that you see in the dashboard for your rig.

Now, run the script. You should get an output that's something like this:

Lock acquired for rig with name 'my-rig-name'

Now, let's explore what just happened...

Rig Locking ​

A Rockface rig is exclusively usable by one user at a time. This allows tests to be run in isolation from each other, safe from the influence of other tests or users trying to use the same rig.

Rockface ensures that there can only be one user of a rig at a time using a lock and a queue for that lock. When users request exclusive access to a rig, they enter the queue. When they reach the front of the queue, they are given the lock, which they release when they're done.

In the code you've just run, we used the function Rig.find_by_name to request exclusive access on the rig with a specific name. This function is a python context manager that produces an object representing a locked rig:

py
with Rig.find_by_name("my-rig-name", ...) as rig:
	# 'rig' is an object representing the locked rig
    ...
What's a "context manager"?

A context manager is a type of python object that can be used with the python with statement. If you're not familiar with them, you can read more about them in the python documentation, or in most good python tutorials.

If you'd prefer not to use a context manager, and would just like to access the rig without having to use one, then you can do this:

py
rig = Rig.find_by_name("my-rig-name", api_key=API_KEY)

The lock on the rig will be dropped when the resulting object is deleted, or when your program finishes.

You can also delay locking the rig to a later point in time, by using the lock argument:

py
rig = Rig.find_by_name("my-rig-name", api_key=API_KEY, lock=False)

with rig:
    # rig is locked within this context

When the with block ends, the context manager ensures that the lock on the rig is released so that the next potential user of the rig can go on to use it.

Inside the with block, we printed out the name of the rig in use using the name property:

py
    print(f"Lock acquired for rig with name '{rig.name}'")

This simply asked the rig to identify itself, and printed the result to your terminal.

Find your tools ​

The object you get back from Rig.find_by_name has a tools property, which is a dict of the tools on your rig. Let's look at that (note that we're eliding the name and API keys below — see above if you missed how to set them):

py
with Rig.find_by_name(...) as rig:
    print(rig.tools)

When you run this, you'll see the set of tools your rig has. For example on our rig, we get:

{'gpio': <rockface.tools.gpio.GPIOTool at 0x7fedbee756c0>,
 'vbus': <rockface.tools.psu.PSUTool at 0x7fedbe2d9e10>,
 'serial': <rockface.tools.usb_serial.USBSerial at 0x7fedbdc470d0>}

In this output, you can see that the keys of the dictionary are string names for each of the tools. These names are set for you by Rockface when your rig is installed (we'll talk to you about what you want them to be). Each of the values in the dictionary represents one tool.

You can see in the output that these values have types that tell you what type of tool they are as well. This is useful when you're first setting up your code to interact with the rig. Once you've done that, it's easier to rely on the string names to get hold of the right tool.

Using a Tool ​

Every rig is a bit different; the tools on yours will differ from those on the the rig we've looked at above. We're going to look at an example of a rig with a power supply tool called "vbus" — so named because on this rig it provides a 5V supply to a USB-powered device.

The same general usage patterns apply across all Rockface tools. If your rig doesn't have a power supply, this demonstration should still be enough to give you an idea of how to interact with other tools.

Here's some example code:

py
from rockface.tools.psu import CurrentLimitMode
from time import sleep

with Rig.find_by_name(...) as rig:
    psu = rig.tools["vbus"]
    print("Power supply specification:", psu.spec)

    # Set the output voltage setpoint (in volts)
    psu.config.voltage = 5

    # Set the current limit (in amps)
	psu.config.current_limit = 0.5

    # The default current limit mode is 'trip'
	psu.config.current_limit_mode = CurrentLimitMode.LIMITING

    # Turn on the supply
	psu.enable = True
	sleep(1)

    print(f"DUT is drawing {psu.current}A from a {psu.voltage}V supply")

In this example we looked-up the power supply tool we wanted from the rig's tools dict. Then we displayed the specification of the power supply. This resulted in some output that looked like this:

Power supply specification:
voltage=VoltageCapabilities(sense_resolution=0.01, min=0.0, max=5.25)
current=CurrentRange(min=0.0, max=0.5)

This specification tells us that our power supply tool can provide any voltages between 0 and 5.25V, and can have its current limit set up to 0.5A.

Next, we modified a few aspects of the power supply's config property. We set its output voltage to 5V, its current limit to 0.5A, and we also set the current limit "mode" to "limiting". For more information on what a "limiting current limit mode" is, refer to the power supply's documentation.

Finally, we turned the power supply on by setting its enable property to True, waited one second, and then displayed the current and voltages that the power supply was sensing. In our case we got an output like this:

DUT is drawing 0.23A from a 5V supply

Reset ​

At the end of the last example piece of code, the power supply we were using was still enabled. Does this mean that the power supply will continue to be enabled forever, or until someone comes along and turns it off? No! When the lock on the rig is released, the rig will reset all of its tools back to their most default inactive state.

So when the with block ended, our code released the lock, which caused the power supply to be turned off. This ensures that our tests start from a known state, no matter what any previous sessions that used the rig did to it.

Explore the other tools ​

Hopefully this tutorial has given you the general idea of how to use the Rockface tooling. Your rig will have several tools that have not been covered by this tutorial. You'll find guidance on how to use these in the side menu of this documentation under the heading "Tools: How to use".