2. Tutorial

This tutorial demonstrates how to work with client code. For the Command-line interface, there is a different tutorial.

Begin by getting an API token (from the Web UI). There are several ways to make it available to the client code. In this example, we assume that it is saved to a file named jwt.txt. Instantiate APIClient with this token:

import rerobots.api

with open('jwt.txt') as fp:
    apic = rerobots.api.APIClient(api_token=fp.read())

Get a list of all workspace deployments that involve “misty” (i.e., robots by Misty Robotics):

apic.get_wdeployments(query='misty')

yielding a list like

[{'id': '2c0873b5-1da1-46e6-9658-c40379774edf', 'type': 'fixed_misty2'},
 {'id': '3a65acd4-4aef-4ffc-b7f9-d50e48fc5541', 'type': 'basic_misty2fieldtrial'}]

The list you receive might be different, depending on availability of workspace deployments. To get more information about one of them, call get_wdeployment_info(), for example:

apic.get_wdeployment_info('3a65acd4-4aef-4ffc-b7f9-d50e48fc5541')

which will return a Python dict like

{'id': '3a65acd4-4aef-4ffc-b7f9-d50e48fc5541',
 'type': 'basic_misty2fieldtrial',
 'type_version': 1,
 'supported_addons': ['cam', 'mistyproxy', 'drive'],
 'desc': '',
 'region': 'us:cali',
 'icounter': 886,
 'created': '2019-07-28 23:26:16.983048',
 'queuelen': 0}

Notice that the field supported_addons includes cam. Later in this tutorial, the cam add-on is used to get images from cameras in the workspace.

The Instance class can be used to instantiate from this workspace deployment:

rri = rerobots.Instance(wdeployment_id='3a65acd4-4aef-4ffc-b7f9-d50e48fc5541', apic=apic)

Then, methods on rri will affect the instance just created. For example, to get the status of the instance, call rri.get_status(), which usually begins with 'INIT' (i.e., initializing). The instance is ready for action when rri.get_status() == 'READY'. For more information about it, call rri.get_details() to get a Python dict like

{'type': 'basic_misty2fieldtrial',
 'region': 'us:cali',
 'starttime': '2020-05-23 02:12:16.984534',
 'status': 'READY',
 'conn': {
   'type': 'sshtun',
   'ipv4': '147.75.70.51',
   'port': 2210,
   'hostkeys': ['ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBOBfAaj/HSSl7oJZ+CXnzxFsXnGQZjBh1Djdm8s7V1fdgdiyJn0JrBxzt0pSdcy50JZW+9qc1Msl34YXUjn0mwU= root@newc247']}}

Notice that the connection type is sshtun and that the above host keys should be expected from hosts in the instance.

Recall from earlier in this tutorial that the cam add-on is supported by the workspace. Activate it by calling

rri.activate_addon_cam()

and waiting until rri.status_addon_cam() indicates that it is ready. In practice, activation is completed within several seconds. Then, use get_snapshot_cam() to get an image and save it in a NumPy ndarray, and display it with Matplotlib:

import matplotlib.pyplot as plt
import numpy as np

res = rri.get_snapshot_cam(dformat='ndarray')

plt.imshow(res['data'])
plt.show()

The resulting figure should open in a separate window.

Though not as powerful as dedicated ssh command-line programs, the Instance class provides methods for basic operations over SSH. To begin, start an ssh client:

rri.start_sshclient()

Then, arbitrary commands can be executed on the host in the instance via exec_ssh. For example,

rri.exec_ssh('pwd')

will return the default path from which commands are executed. Files can be uploaded and downloaded using put_file, and get_file, respectively. For example, to download the file /etc/hosts from the remote host:

rri.get_file('/etc/hosts', 'hosts')

Finally, to stop using the instance and delete your data from it,

rri.terminate()