Command Line Interface

$ ./empower-ctl.py
usage: ./empower-ctl.py [options] command [command options]

optional arguments:
  -h, --help            show this help message and exit
  -r HOST, --host HOST  REST server address; default='127.0.0.1'
  -p PORT, --port PORT  REST server port; default=8888
  -u USER, --user USER  EmPOWER admin user; default='root'
  -a AUTH, --auth AUTH  EmPOWER admin user:passw
  -n, --no-passwd       Run without password; default false
  -f PASSWDFILE, --passwd-file PASSWDFILE
                        Password file; default=none
  -t TRANSPORT, --transport TRANSPORT
                        The transport (http/https); default='http'

Available commands are:
   add-vbs                       Add a new VBS.
   add-wtp                       Add a new WTP.
   create-project                Create a new project.
   del-vbs                       Del a VBS.
   del-wtp                       Del a WTP.
   delete-lte-slice              LTE Slices CLI tools.
   delete-project                Delete a project.
   delete-wifi-slice             WiFi Slices CLI tools.
   list-apps                     List currently running applications.
   list-apps-catalog             List currently running applications.
   list-lte-slices               LTE Slices CLI tools.
   list-projects                 List projects.
   list-vbses                    List VBSes.
   list-wifi-slices              WiFi Slices CLI tools.
   list-workers                  List currently running workers.
   list-workers-catalog          List workers that can be loaded.
   list-wtps                     List WTPs.
   load-app                      List currently running applications.
   load-worker                   Load a worker.
   set-app-callback              Set app callback.
   set-app-params                Set application parameters.
   set-worker-callback           Set worker callback.
   set-worker-params             Set worker parameters.
   unload-all-apps               Unload all applications.
   unload-all-workers            Unload all worker.
   unload-app                    Unload an application.
   unload-worker                 Unload a worker.
   unset-app-callback            Unset app callback.
   unset-worker-callback         Unset worker callback.
   upsert-lte-slice              LTE Slices CLI tools.
   upsert-wifi-slice             WiFi Slices CLI tools.

See './empower-ctl.py help <command>' for more info.

The CLI used the controller REST interface to execute the commands. By default, the CLI tries to connect to localhost:8888. You can change this using the --host and --port options:

$ ./empower-ctl.py --host=127.0.0.1 --port=8888

By default, the CLI tries to execute the commands as root prompting the user for the password. You can specify another user using the --user. You can also prevent the CLI to prompt for the password using the --no-passwd options. This last option can be used if you know that the command will not require a password (e.g. read-only commands do not require a password).

Each of the various commands supported by the CLI has its help. For example, the list-wtps does not have any additional parameter:

$ ./empower-ctl.py help list-wtps
usage: empower-ctl.py list-wtps

List WTPs.

optional arguments:
  -h, --help  show this help message and exit

Conversely, the list-apps command requires the user to specify the project id:

$ ./empower-ctl.py help list-apps
usage: empower-ctl.py list-apps <options>

List active apps.

optional arguments:
  -h, --help            show this help message and exit

required named arguments:
  -p PROJECT_ID, --project_id PROJECT_ID
                        The project id

Create devices

You can add a new WTP/VBS using add-wtp/add-vbs command:

usage: empower-ctl.py add-wtp <options>

Add a new WTP.

optional arguments:
  -h, --help            show this help message and exit
  -d DESC, --desc DESC  A human readable description of the device

required named arguments:
  -a ADDR, --addr ADDR  The device address

For example, the following command adds a new WTP:

$ ./empower-ctl.py add-wtp --addr="00:0D:B9:2F:56:88"

The output should be something like this:

addr 00:0D:B9:2F:56:88 desc "Generic device" ADDED

It is also possible to specify a custom description:

$ ./empower-ctl.py add-wtp \
  --addr="00:0D:B9:2F:56:89" \
  --desc="Access Point Second Floor East"

The output should be something like this:

addr 00:0D:B9:2F:56:89 desc "Access Point Second Floor East" ADDED

List devices

You can list the currently registered WTPs/VBSes with list-wtps/list-vbses command:

$ ./empower-ctl.py -n list-wtps
  --desc="Access Point Second Floor East"

The output should be something like this:

addr 00:0D:B9:2F:56:88 desc "Generic device"
addr 00:0D:B9:2F:56:89 desc "Access Point Second Floor East"

Delete devices

You can remove a WTPs/VBSes with del-wtp/del-vbs command:

$ ./empower-ctl.py del-wtp \
  --addr=00:0D:B9:2F:56:88 \
  --desc="Access Point Second Floor East"

The output should be something like this:

Device id 00:0D:B9:2F:56:88 DELETED

Create projects

You can create a new project using create-project command:

$ ./empower-ctl.py help create-project
usage: empower-ctl.py create-project <options>

Create a new project.

optional arguments:
  -h, --help            show this help message and exit
  -p PLMNID, --plmnid PLMNID
                        The network PLMNID; default=None
  -s SSID, --ssid SSID  The network SSID; default=None
  -t {unique,shared}, --ssid_type {unique,shared}
                        The network SSID type; default=unique

required named arguments:
  -d DESC, --desc DESC  The project description
  -o OWNER, --owner OWNER
                        The project owner

Most probably you want to specify either the ssid or the plmnid option. Specifying only the ssid or the plmnid options will make the project, respectively, a Wi-Fi-only or an LTE-only project. It is possible to specify both options at the same time. It is also recommended to specify at least one of them at the creation time since those options cannot be modified at a later stage.

For example, the following command creates a new Wi-Fi project with SSID set to "EmPOWER" and assigns the user foo as its manager:

$ ./empower-ctl.py create-project \
  --desc="My Project" \
  --owner="foo" \
  --ssid="EmPOWER" \
  --desc="Access Point Second Floor East"

The output should be something like this:

project_id 0af0483e-960f-4dc3-b997-d6380f3db6b1
  desc: My Project
  wi-fi properties
    ssid: EmPOWER
    bssid Type: unique

List Projects

You can list the currently defined projects with the list-projects command:

$ ./empower-ctl.py -n list-projects

The output should be something like this:

project_id 0af0483e-960f-4dc3-b997-d6380f3db6b1
  desc: My Project
  wi-fi properties
    ssid: EmPOWER
    bssid Type: unique

Delete Projects

You can delete a project with the delete-project command:

$ ./empower-ctl.py delete-project \
  --project-id=0af0483e-960f-4dc3-b997-d6380f3db6b1

The output should be something like this:

project id 0af0483e-960f-4dc3-b997-d6380f3db6b1 DELETED

Starting apps and workers

Apps are services bound to a certain project. Conversely, workers are services that are not bound to any project. You can think of workers as system daemons performing a certain task in the background and apps as general-purpose applications executed by a certain user of a system.

The Developers section of this Wiki explains how to write new apps and workers in this section we will show how to list, start, and stop them using the CLI.

You can list the apps that can be loaded using the list-apps-catalog command:

$ ./empower-ctl.py -n list-apps-catalog

The output should be something like this:

name empower.apps.mcast.mcast
  desc: SDN@Play Multicast Manager.
  params:
    every: The control loop period (in ms). Default: 2000. Type: int. Mandatory: False.
name empower.apps.wifimobilitymanager.wifimobilitymanager
  desc: A simple Wi-Fi mobility manager.
  params:
    every: The control loop period (in ms). Default: 2000. Type: int. Mandatory: False.
name empower.primitives.lvapbincounter.lvapbincounter
  desc: LVAP Bin Counter Primitive.
  params:
    sta: The LVAP to monitor. Type: EtherAddress. Mandatory: True.
    bins: The bins for the measurements (comma separated). Default: 8192. Type: list. Mandatory: False.
    every: The control loop period (in ms). Default: 2000. Type: int. Mandatory: False.
name empower.primitives.txpbincounter.txpbincounter
  desc: TXP Bin Counter Primitive.
  params:
    iface_id: The Wi-Fi interface. Type: int. Mandatory: True.
    addr: The address to monitor. Type: EtherAddress. Mandatory: True.
    bins: The bins for the measurements (comma separated). Default: 8192. Type: list. Mandatory: False.
    every: The control loop period (in ms). Default: 2000. Type: int. Mandatory: False.
name empower.primitives.wifircstats.wifircstats
  desc: WiFi Rate Control Statistics Primitive.
  params:
    sta: The LVAP to monitor. Type: EtherAddress. Mandatory: True.
    every: The control loop period (in ms). Default: 2000. Type: int. Mandatory: False.
name empower.primitives.wifislicestats.wifislicestats
  desc: WiFi Rate Control Statistics Primitive.
  params:
    slice_id: The slice to monitor. Default: 0. Type: int. Mandatory: False.
    every: The control loop period (in ms). Default: 2000. Type: int. Mandatory: False.
name empower.apps.helloworld.helloworld
  desc: Hello! World app.
  params:
    message: The message to be printed. Default: World. Type: string. Mandatory: False.
    every: The control loop period (in ms). Default: 2000. Type: int. Mandatory: False.

Likewise, you can list the workers that can be loaded using the list-workers-catalog command:

$ ./empower-ctl.py -n list-workers-catalog

The output should be something like this:

name empower.workers.wifichannelqualitymap.wifichannelqualitymap
  desc: WiFi Channel Quality Map Worker.
  params:
    every: The control loop period (in ms). Default: 5000. Type: int. Mandatory: False.
name empower.workers.wifichannelstats.wifichannelstats
  desc: WiFi Channel Statistics Worker.
  params:
    every: The control loop period (in ms). Default: 5000. Type: int. Mandatory: False.

You can load an app with the following command:

$ ./empower-ctl.py load-app \
  --project_id=52313ecb-9d00-4b7d-b873-b55d3d9ada26 \
  --name=empower.apps.helloworld.helloworld

The output should be something like this:

app id 5ee18d75-ae18-41dd-b8a2-1fc9cc5fdc6d status RUNNING
  name: empower.apps.helloworld.helloworld
  params:
    message: World
    every: 2000
    service_id: 5ee18d75-ae18-41dd-b8a2-1fc9cc5fdc6d
    project_id: 52313ecb-9d00-4b7d-b873-b55d3d9ada26

You can load a worker with the following command (notice how the project_id option is not needed in this case):

$ ./empower-ctl.py load-worker \
  --name=empower.workers.wifichannelstats.wifichannelstats

The output should be something like this:

worker id 9d75fddd-9fec-47f8-bd5e-0cb36b1579d6 status RUNNING
  name: empower.workers.wifichannelstats.wifichannelstats
  params:
    every: 2000
    service_id: 9d75fddd-9fec-47f8-bd5e-0cb36b1579d6
    project_id: 3a4fc897-c548-4e07-ad6d-ffc23bbe27c7

You can list the apps that are currently running within a certain project using the list-apps command:

$ ./empower-ctl.py list-apps \
  --project_id=52313ecb-9d00-4b7d-b873-b55d3d9ada26

The output should be something like this:

app id 5ee18d75-ae18-41dd-b8a2-1fc9cc5fdc6d status RUNNING
  name: empower.apps.helloworld.helloworld
  params:
    message: World
    every: 2000
    service_id: 480a9843-8b38-434b-9a9c-ad5deb2de263
    project_id: 52313ecb-9d00-4b7d-b873-b55d3d9ada26

Likewise, you can list the active workers using the list-workers command:

$ ./empower-ctl.py list-workers

The output should be something like this:

worker id 9d75fddd-9fec-47f8-bd5e-0cb36b1579d6 status RUNNING
  name: empower.workers.wifichannelstats.wifichannelstats
  params:
    every: 2000
    service_id: 9d75fddd-9fec-47f8-bd5e-0cb36b1579d6
    project_id: 3a4fc897-c548-4e07-ad6d-ffc23bbe27c7

Stopping app and workers

You can unload an app with the following command:

$ ./empower-ctl.py unload-app \
  --project_id=52313ecb-9d00-4b7d-b873-b55d3d9ada26 \
  --app_id=5ee18d75-ae18-41dd-b8a2-1fc9cc5fdc6d

The output should be something like this:

app id 5ee18d75-ae18-41dd-b8a2-1fc9cc5fdc6d status STOPPED

Likewise, you can unload a worker with the following command:

$ ./empower-ctl.py unload-worker \
  --worker_id=9d75fddd-9fec-47f8-bd5e-0cb36b1579d6

The output should be something like this:

worker id 9d75fddd-9fec-47f8-bd5e-0cb36b1579d6 status STOPPED

Configuring apps and workers

Apps and workers can have additional configuration parameters. For example, the helloworld app has an optional parameter that can be used to customize the hello message.

The list of parameters supported by and app or a worker can be seen using the list-apps-catalog/list-workers-catalog commands.

App/workers' parameters are specified after the name of the app/worker. For example, you can change the hello message by launching the app in the following way:

$ ./empower-ctl.py load-app \
  --project_id=52313ecb-9d00-4b7d-b873-b55d3d9ada26 \
  --name=empower.apps.helloworld.helloworld \
  --message=Bob

Apps/workers parameters can also be modified at run time with

$ ./empower-ctl.py set-app-params \
  --project_id=52313ecb-9d00-4b7d-b873-b55d3d9ada26 \
  --app_id=5ee18d75-ae18-41dd-b8a2-1fc9cc5fdc6d \
  --message=Alice