Usage

wa

The root entrypoint for the wa_cli is wa. This the first command you need to access the CLI. All subsequent subcommands succeed wa.

usage: wa [-h] [-v] [--dry-run] {script,docker,wiki,dev} ...

Named Arguments

-v, --verbose

Level of verbosity

Default: 0

--dry-run

Run as a dry run

Default: False

Sub-commands

Subcommands immediately succeed the wa command. They implement additional logic. Having subcommands rather than arguments directly to wa increases expandability as it will allow for additional features to be implemented without convoluting the help menu of the base wa command.

script

Initializer method for the script entrypoint.

This entrypoint serves as a mechanism for running various scripts meant for members of the Wisconsin Autonomous student organization.

usage: wa script [-h] {license} ...

script license

The license command will automatically place headers at the top of each requested file.

usage: wa script license [-h] [--tmpl TMPL] [--years YEARS]
                         [--projname PROJNAME] [--owner OWNER]
                         [--projurl PROJURL] [--ext [EXT [EXT ...]]]
                         dir
Positional Arguments
dir

The directory to recursively process.

Named Arguments
--tmpl

Template file to use. If it is not set, will default to using the template shipped with the package.

--years

Year or year range to use. If not set, will use the 2018-<the current year>.

--projname

Name of the project.

Default: “WA”

--owner

Name of the copyright owner.

Default: “Wisconsin Autonomous”

--projurl

URL of the project.

Default: “https://wa.wisc.edu”

--ext

If specified, restrict processing to the specified extension(s) only.

Default: [‘py’, ‘cpp’]

docker

Initializer method for the docker entrypoint.

The entrypoint serves as a mechanism for running containers with docker. A common desireable usecase for simulations is to have it run in a containerized system; for instance, if a script requiries a certain package, the Docker image could be shipped without needing to install the package on a system locally. The scalability of using Docker over installing packages on a system is much greater.

There are a few ports that may be exposed, and the typical purpose of each port (for wa) is outlined below:

  • 8080: novnc port to display gui apps in a browser.

  • 5900: vnc port for displaying gui apps in a vnc viewer

  • 8888: rosboard visualizer. See their github. This is used for visualizing ROS data

  • 5555: Used by wa_simulator to communicate data over a bridge or to another external entity

There are also a few ip addresses we use and how they are used is seen below:

  • 172.20.0.2: Reserved for the control stack

  • 172.20.0.3: Reserved for the simulation

  • 172.20.0.4: Reserved for vnc

To see specific commands that are available, run the following command:

wa docker -h

usage: wa docker [-h] {run,stack,vnc,network} ...

docker run

The run command will spin up a Docker container that runs a python script with the desired image.

The use case for the run command is when we’d like to run a simulation script with a certain operating system configuration or in a way that’s distributable across computers. Everyone’s setup is different, i.e. OS, development environment, packages installed. Using Docker, you can simply run wa docker run... and run any script agnostic from your local system.

The run command requires one argument: a python script to run in the container. The python script is the actual file we’ll run from within the container. After the python script, you may add arguments that will get passed to the script when it’s run in the container.

Example cli commands:

# Run from within wa_simulator/demos/bridge
# Running wa_simulator/demos/bridge/demo_bridge_server.py using command line arguments
# This should be used to communicate with a client running on the host
wa docker run \
        --name wasim-docker \
        --image wiscauto/wa_simulator:latest \
        --network "wa" \
        --data "../data:/root/data" \ # ':root/data' not really necessary
        --data "pid_controller.py" \  # Will be resolved to an absolute path automatically
        --port "5555:5555" \
        demo_bridge_server.py --step_size 2e-3

# Or more simply, leveraging provided by 'wasim'
wa docker run \
        --wasim \
        --data "../data:/root/data" \
        --data "pid_controller.py" \
        demo_bridge_server.py --step_size 2e-3

# Leverage defaults, but using the develop image
wa docker run \
        --wasim \
        --image wiscauto/wa_simulator:develop \
        --data "../data:/root/data" \
        --data "pid_controller.py" \
        demo_bridge_server.py --step_size 2e-3

usage: wa docker run [-h] [--name NAME] [--image IMAGE] [--data DATA]
                     [--port PORT] [--env ENVIRONMENT] [--network NETWORK]
                     [--ip IP] [--wasim] [--no-vnc]
                     script ...
Positional Arguments
script

The script to run up in the Docker container

script_args

The arguments for the [script]

Named Arguments
--name

Name of the container.

--image

Name of the image to run.

--data

Data to pass to the container as a Docker volume. Multiple data entries can be provided.

Default: []

--port

Ports to expose from the container.

Default: []

--env

Environment variables.

Default: []

--network

The network to communicate with.

--ip

The static ip address to use when connecting to ‘network’. Used as the server ip.

--wasim

Run the passed script with all the defaults for the wa_simulator. Will set ‘DISPLAY’ to use vnc.

Default: False

--no-vnc

Don’t implicitly create a vnc server. Not to be confused with noVNC.

Default: False

docker stack

Command that essentially wraps docker-compose and can help spin up, attach, destroy, and build docker-compose based containers.

This command is completely redundant; it simply combines all the build, spin up, attach or destroy logic in a single command. The usage here is for Wisconsin Autonomous members to quickly start and attach to control stack docker containers that are based on the typical docker-compose file that we use.

There are four possible commands that can be used using the stack subcommand: build, up, down, and attach. For example, if you’d like to build the container, you’d run the following command:

wa docker stack --build

If you’d like to build, start the container, then attach to it, run the following command:

wa docker stack --build --up --attach
# OR (shorthand)
wa docker stack -b -u -a
# OR
wa docker stack -bua

If no arguments are passed, this is equivalent to the following command:

wa docker stack --up --attach

If desired, pass --down to stop the container. Further, if the container exists and changes are made to the repository, the container will not be built automatically. To do that, add the --build argument.

usage: wa docker stack [-h] [-b] [-u] [-d] [-a]
Named Arguments
-b, --build

Build the stack.

Default: False

-u, --up

Spin up the stack.

Default: False

-d, --down

Tear down the stack.

Default: False

-a, --attach

Attach to the stack.

Default: False

docker vnc

Command to spin up a vnc docker container to allow the visualization of GUI apps in docker

noVNC is a tool for using VNC in a browser. docker-vnc is a docker container that’s been created that runs vnc and can be used to visualize gui applications for other docker containers in a browser or via a vnc viewer. There are a few requirements to ensure gui apps are correctly visualized, as seen below:

  • network: Docker networks are used to help containers communicate with other containers or with the host. When spinning up a container that you want to visualize a gui app with vnc, you will need to make sure it is connected to the same network as the vnc container, i.e. make sure the original container is connected to the same network that you passed to --network (or the default wa network).

  • port: The novnc instance can be visualized in your browser at http://localhost:8080/vnc_auto.html. As seen in the url, the application is hosted on port 8080. This port must then be exposed from the container to the host. This is again done by the wa docker novnc command. Furthermore, to visualzie the apps in a vnc viewer, 5900 also has to be exposed.

  • DISPLAY: The DISPLAY environment variable is used to help display applications in X window systems (used by any linux based container, like the ones we use). To make sure the gui apps are visualized in vnc when the aforementioned requirements are setup, you need to make sure the DISPLAY variable is set correctly. The variable should be set to vnc:0.0 (assuming the vnc container that has been setup is named ‘vnc’).

usage: wa docker vnc [-h] [--name NAME] [--network NETWORK] [--ip IP] [--stop]
Named Arguments
--name

Name of the container.

Default: “vnc”

--network

The network to communicate with.

Default: “wa”

--ip

The static ip address to use when connecting to ‘network’.

Default: “172.20.0.4”

--stop

Stop the vnc container.

Default: False

docker network

Command to start a docker network for use with WA applications

To create complicated docker systems, networks are a common mechanism. They allow multiple docker containers to be used together, where each implements its own features and is isolated, outside of its communication between each other. Example use cases are one container for wa_simulator, one for vnc for visualizing gui apps, and one for ros to run control logic, where each communicator is on the same network and allows for each container to send data between each other.

This command will initialize a container with defaults that are typical for WA applications.

usage: wa docker network [-h] [--name NAME] [--ip IP]
Named Arguments
--name

Name of the network to create.

Default: “wa”

--ip

The ip address to use when creating the network. All containers connected to it must be in the subnet 255.255.255.0 of this value.

Default: “172.20.0.0”

wiki

Initializer method for the wiki entrypoint.

This entrypoint serves as a mechanism for running helpers that relate to the wiki website at WisconsinAutonomous.github.io.

usage: wa wiki [-h] {post,dev} ...

wiki post

The post command will create a post template for the Wisconsin Autonomous Wiki.

The Wiki is located at WisconsinAutonomous.github.io and is a jekyll site that creates website pages from markdown code.

For information on creating a new post, see this page.

This command a generated post template similar to the following:

---
title: New Post
author: Your Name
date: 2021-01-11 00:00:00 -0600
categories: [Introduction, Wiki Tutorials]
tags: [tutorials, templates, non-technical]
---

This is a template for a new post for this site. Feel free to copy this markdown directly to your new file.

## Setup Guide


## Support

Contact [Your Name](mailto:wiscid@wisc.edu) for any questions or concerns regarding the contents of this post.

## See Also

Stay up to date with our technical info by following our [blog](https://wa.wisc.edu/blog).

Follow us on [Facebook](https://www.facebook.com/wisconsinautonomous/), [Instagram](https://www.instagram.com/wisconsinautonomous/), and [LinkedIn](https://www.linkedin.com/company/wisconsin-autonomous/about/)!

![WA Logo](/assets/img/logos/wa-white.png){: .left height="100"}
![Wisconsin Crest](/assets/img/logos/uw-crest.png){: .right height="100"}

usage: wa wiki post [-h] --title TITLE [--author AUTHOR]
                    [--category CATEGORIES] [--tag TAGS] [--email EMAIL]
Named Arguments
--title

The title of the post.

--author

The author to use for the post.

Default: “Wisconsin Autonomous”

--category

The categories to mark on the post

Default: []

--tag

The tags to mark on the post

Default: []

--email

Email to use in the post.

Default: “wisconsinautonomous@studentorg.wisc.edu”

wiki dev

The dev command spins up a docker container that serves up a local build of the wiki at https://localhost:4000

To test changes locally, from within the root directory of the WisconsinAutonomous.github.io, run wa wiki dev. This will build the wiki pages locally. Ensure this is done before pushing to github.

usage: wa wiki dev [-h]