TWIST.Wireless Getting started

Get an account

In order to authenticate to twist-AM you need to sign up for an account at the iMinds authority. On the right side of the registration form select ‘Join Existing Project’ or create a new one. Joining a project will trigger a request to the projects lead and you’ll need to be approved before your account is being enabled.

After you received notice about your account activation, navigate to the page again and login. You now have the opportunity to download a certificate. Select the first option at this point and save the certificate somewhere on your machine. Note: pass-phrase for the certificate is the same as the account password.

jFed-experimenter GUI

Get started with jFed Experimenter GUI

Please refer to get started with jFed for more detailed information or download jFed Experimenter GUI directly from download page.

Install Oracle Java

jFed requires Oracle Java 8 to run. OpenJDK and earlier versions of Java are not supported. Follow the guide to install it.

Initialize jFed experimenter

After downloading start the GUI by executing java -jar jFed-experimenter-GUI.jar.

In the login dialog select the certificate you downloaded earlier and enter your iMinds password. After clicking on login you will be asked to make initial settings. For automated upload of the public key to the reserved nodes add your key in the settings.

Note: under SSH Authentication ‣ Use custom key-pair you can provide own private ssh key. There is also one included by default in the certificate. Proper key selection is necessary for SSH login into the nodes in later stages of this tutorial.

After clicking on save, the GUI will show up and you can start to setup your first experiment.

Create your first experiment

When you click New, you get a blank canvas where you can draw your experiment. Drag in a Wireless node from the left side to the canvas.

Experiment canvas

To select ‘TWIST’ as the testbed right click on the node and click ‘Configure Node’.

  • In the Properties dialog select ‘TWIST’ as the testbed from the dropdown menu

  • In the Node selection dialog you can either select a specific node or just let the AM assign any available

  • It is possible to use default disk image (leave option empty) or provide custom built one that suits your personal purpose.

    Disk images can be created with the Creating custom disk images tutorial and provided as http link that will be available by the TWIST testbed to download from.

After clicking on save you can repeat this procedure and select as many nodes as your experiment requires. To avoid having to reassemble your setting every time you can always Save your experiment as an rspec file and reload it the next time you open jFed-experimenter.

Select TWIST testbed

Run the experiment

Run this experiment, by clicking the tab General at the top, and then the Run button. You will now have to choose a name for the experiment (= slice name) and choose a maximum duration. It will now take a couple of minutes to get the node prepared.

Create a slice

When you see a green check box in front of ‘Waiting for nodes from TWIST to become ready’ you can now log in to the nodes using your private key. This can be achieved by either right clicking on the node ‣ Open SSH terminal in jFed or executing ssh -F ssh.cfg -i <iminds.pem or id_rsa> <nodeid> using downloaded ssh.cfg.

Ready to login

It is possible to use Ansible to further automate the experiment configuration. Please refer to WirelessTestbedsAcademy/ExperimentationTools for further information and usage template.

Release the nodes

When you have finished your experiment, don’t forget to click the red Terminate button to release your nodes. This way they are available for other experimenters again. Keep in mind that this will reboot the node and all changes you may have made are lost irreversibly. Also your nodes will expire together with your slice. iMinds will send you a notification and you can renew your slice, if your experiment takes longer than expected though.

Omni cli

Install omni as part of geni-tools

Follow the official instructions to install omni.

Configure omni for use with TWIST-AM

Download the configuration template here and copy it to ~/.gcf/omni_config. Replace the placeholders to configure omni for your iMinds account.

Test your configuration:

omni -a twist getversion

Run the experiment

We assume you have a valid rspec file describing your experiment setup. You can use jFed-experimenter to configure the experiment and export the corresponding rspec file. Say the filename is experiment.rspec.

omni -a twist createslice name_of_slice
omni -a twist renewslice name_of_slice YYYY-MM-DDTHH:MM:SS #optionally extend expiration time
omni -a twist allocate name_of_slice experiment.rspec
omni -a twist provision name_of_slice experiment.rspec

This last call starts a long-running process. You can repeatedly poll the status of the reservation:

omni -a twist status name_of_slice

Wait until all nodes have transitioned from operational_status:geni_pending_allocation to operational_status:geni_notready. During the process a node might fail, indicated by operational_status:geni_failed. You can drop that node from your reservation now in order to continue with the others. Check the output of status and identify the sliver which has failed. Copy the geni_sliver_urn and delete it from the slice:

omni-docker -a twist_test delete testslice -u

Poll the status until the node has disappeared from the slice.

When all nodes of the slice are geni_notready, you can start them:

omni -a twist poa name_of_slice geni_start

Use the status call to poll for operational_status:geni_ready. If a node fails repeat the procedure described above to delete it from the slice.

When all nodes are ready, you can get more details using

omni -a twist describe name_of_slice

This will provide positions, mac addresses and login information.