JaiaBot 3.0.0
JaiaBot micro-AUV software
Loading...
Searching...
No Matches
Jaia Tool

The jaia command line tool aims to be the single entry point for all advanced configuration and administration of JaiaBots and Hubs.

Usage

The jaia tool has numerous actions (some of which have subactions of their own). To see the full list of actions available, type:

jaia help

To see the options of an action, you can type (for example, the version action):

jaia help version

This works recursively for any child action, e.g.,

jaia admin ssh help add

Common Concepts

Many of the actions (jaia ip, jaia ping, jaia ssh) act on another (remote) host (Bot or Hub). The remote host is specified using a shorthand that encodes the host type (bot or hub), ID, network, and fleet ID.

At its simplest the shorthand is bNfM for Bot N on fleet M or hIfJ for Hub I on Fleet J. This uses the local network for fleet operations.

Bots or Hubs may be connected via the Cloud (see the Cloud Computing page for more details) or via the service VPN for remote support. In these cases a character before the fleet 'f' is used to indicate the network in use:

  • s - service VPN (vpn.jaia.tech)
  • v - VirtualFleet VPN (for virtual bots/hubs)
  • c - CloudHub VPN (for remote bots/hubs).

Thus, Bot 5 on VirtualFleet 3 would be b5vf3, or (real) Hub 1 Fleet 10 via the Cloud would be h1cf10. For servicing hosts remotely, Bot 2 on Fleet 4 would be b2sf4.

This section written by Claude

Additionally, if you are on a bot or hub, you can omit fN and the current fleet will be used. The fleet is taken from the jaia_fleet_id environmental variable, which login shells pick up from /etc/profile.d/jaia.sh (which reads /etc/jaiabot/jaia.env, written from the debconf database when jaiabot-embedded is configured). Where no profile has been sourced — for example under cron or ssh <host> <command> — the fleet is read from the hostname instead (hub0-fleet3).

This section written by Copilot

The host shorthand format is b<bot_id>[svc]f<fleet_id>, h<hub_id>[svc]f<fleet_id> or chf<fleet_id> (for CloudHub); the f<fleet_id> portion may be omitted as described above. Parsing is implemented in jaiabot::parse_host_code (src/lib/utils/ip.h).

Special cases

Several special cases exist for the host string:

  • "CloudHub" can be referred to as chfM for fleet M
  • "self" can be used to refer to the machine that jaia is being run on (that is, localhost).
  • "xxx.jaia.tech" is passed through unmodified (vpn.jaia.tech, packages.jaia.tech).

ip, ping, ssh

These related commands provide remote functionality using host codes given above.

jaia ip <host> simply gives the IP address for a given host code, e.g.,

  • jaia ip b1sf2 - Bot 1 Fleet 2 via service VPN
  • jaia ip h3vf1 - Hub 3 VirtualFleet 1
  • jaia ip b4 - Bot 4 for the same fleet as the machine this was run on.

This section written by Claude

jaia ip is a thin wrapper around the standalone jaia_ip binary, which can also be run directly (jaia_ip b1sf2). jaia_ip does not load the jaia tool (or goby/protobuf) and so starts up considerably faster; prefer it in scripts and other non-interactive callers that query many addresses. jaia_ip additionally supports an explicit query mode (jaia_ip --query_type net --fleet_id 3 --ip_net fleet_vpn); see jaia_ip --help. Both modes give the address in whichever IP version the fleet uses on the network asked for; --ip_version ipv4 or --ip_version ipv6 asks for one in particular, and works with a host code too (jaia ip b5sf3 --ip_version ipv6). The rest of the explicit mode flags cannot be combined with a host code, which already names the node, its fleet and its network.

jaia ssh uses the same codes but runs ssh to remotely log into the given system. Any parameters passed after the host code is passed unmodified to SSH:

  • jaia ssh b3f5 - SSH into Bot3 on Fleet 5
  • jaia ssh b3f5 -A - SSH into Bot3 on Fleet 5 using ssh -A (i.e., Forwarding of connections from ssh-agent).
  • jaia ssh b4 - SSH into Bot 4 on this fleet.

jaia ping is just like jaia ssh but runs ping to check connectivity to a host. Similarly, all parameters after the host code are appended to the ping command line unmodified.

version

On a given system the version action provides the software version of the jaiabot code and its primary dependencies (Goby, MOOS, IvP, etc.).

  • jaia version - list all versions
  • jaia version --format=json list all versions in JSON
  • jaia version jaiabot lists just the jaiabot version.

As usual, jaia help version gives the full set of options.

Keep in mind that you can pair jaia ssh with any command to execute it remotely. For example, to see the versions of jaiabot and friends running on CloudHub for Fleet 1:

jaia ssh chf1 jaia version

status

jaia status provides a summary of the systemd status of the JaiaBot services (this is the same output you receive on the SSH login MOTD).

ctl

This is a thin wrapper around systemctl for jaiabot services.

  • sudo jaia ctl stop - same as sudo systemctl stop jaiabot
  • sudo jaia ctl start - same as sudo systemctl start jaiabot
  • sudo jaia ctl restart - same as sudo systemctl restart jaiabot
  • sudo jaia ctl restart jaiabot_goby_gps - same as sudo systemctl restart jaiabot_goby_gps

As always, you can use jaia ssh to execute remotely, e.g. to restart all services on Bot1 for Fleet10:

jaia ssh b1f10 sudo jaia ctl restart

doc

This section written by Copilot

jaia doc provides command line access to this documentation (Markdown). Run with no arguments to list all the available pages, or provide a page name to display it in the terminal.

admin

This section written by Copilot

These subactions are used to administer a fleet of JaiaBots:

  • jaia admin ssh manages SSH keys for a given host. See the SSH Access page for more details.
  • jaia admin fleet creates and manages fleet configurations. See the Embedded Board Deployment page for more details.
  • jaia admin debconf reads and writes this bot/hub's own configuration, as described below.
  • jaia admin bounds reports the valid id ranges, as described below.

bounds

This section written by Claude

The bot, hub and fleet id ranges are defined once, in src/lib/utils/ip.h, and this subaction is how a caller outside that header asks what they are rather than hardcoding them:

jaia admin bounds
bot id: [0 150]
hub id: [0 30]
fleet id: [0 4000]
ipv4 fleet id: [0 250]
desktop id: [1 9]
gateway id: [0 0]
rpicam id: [0 49]
cloudhub id: 30

ipv4 fleet id is the part of the fleet id range that is addressed with IPv4 on the fleet WLAN and fleet VPN; the rest is addressed with IPv6 on every network (see Cloud Computing).

Pass one or more ids to narrow the output (--bot_id, --hub_id, --fleet_id, --ipv4_fleet_id, --desktop_id, --gateway_id, --rpicam_id), and --min or --max to select one end. A single id that comes out as a single number is written bare, so a script can use it directly:

jaia admin bounds --bot_id --max
150

cloudhub id is the odd one out: the CloudHub is always hub 30, on every fleet, so it is one id rather than a range and --cloudhub_id on its own already gives a bare 30.

--format json gives the same information as an object, as elsewhere in the tool:

jaia admin bounds --hub_id --format json
{
"hub_id": { "min": 0, "max": 30 }
}

As with jaia ip, this is a thin wrapper around a standalone binary (jaia_bounds) that does not load goby/protobuf; prefer calling that directly from scripts. jaia-update-dns.sh uses it to enumerate the fleet's names.

debconf

This section written by Claude

The jaiabot-embedded debconf database is the single source of truth for a bot or hub's configuration, and the generated systemd units are derived from it. This subaction reads and writes it without having to go through the interactive dpkg-reconfigure menus. Questions are named without the jaiabot-embedded/ prefix.

jaia admin debconf list
jaia admin debconf get fleet_id
jaia admin debconf set fleet_id 3

Reading and writing the debconf database requires root, so get and set re-run themselves under sudo when they are not already root - there is no need to remember to prepend it. (list does not, since it does not read the database.)

get with no question reports what everything is currently set to, which is the counterpart to list's "what can I set?":

QUESTION VALUE
bot_id (unset)
comms_links xbee,wifi
fleet_id 3
type bot

Questions that have never been answered show as (unset), which is distinct from one deliberately set to the empty string. Unlike jaia-debconf.sh selections - which emits debconf-set-selections format for another machine to re-import - this is meant for reading.

--format json gives the same information in a form a machine can read, which is how the Ansible playbooks (config/ansible/tasks/read-debconf.yml) learn what a bot or hub is configured as. Unanswered questions are null:

jaia admin debconf get --format json
{
"bot_id": null,
"comms_links": "xbee,wifi",
"fleet_id": "3",
"type": "bot"
}

A single question in JSON gives an object with just that entry (jaia admin debconf get fleet_id --format json).

list shows every question the package defines, along with its type, default and permitted choices - that is, what you can pass to get and set:

QUESTION TYPE DEFAULT CHOICES
additional_sensors multiselect none turner_c_fluor, turner_c_fluor_2, aml, ppk, none
arduino_type select none spi, usb, none
bot_id string 0
bot_type select hydro hydro, pam, bio, none
...

list reads the package's templates rather than the debconf database, so it describes what can be set. Both list and a bare get take --all, which also shows the internal debconf_state_* questions - those record where the interactive menu is rather than any configuration.

set validates the value against that question's permitted Choices, so a typo fails immediately rather than silently generating the wrong services. The bot_id, hub_id and fleet_id questions have too many valid answers to list as choices, so they are strings whose ranges are checked against jaia admin bounds instead. By default it then runs dpkg-reconfigure jaiabot-embedded, which regenerates and re-enables the systemd units so the change takes effect.

When changing several values, skip the reconfigure on all but the last so the units are only regenerated once:

jaia admin debconf set imu_type bno085 --reconfigure false
jaia admin debconf set bot_type pam

As with any action, these can be run remotely:

jaia ssh b1f10 jaia admin debconf get imu_type