Ubuntu

Install the Agent

Set up Rocos' repository

1. Add Rocos' official GPG key:

   sudo apt update
   sudo apt install --no-install-recommends --yes ca-certificates curl gpg
   sudo mkdir -p /etc/apt/keyrings
   curl -fsSL https://packages.rocos.io/apt/docs/key.gpg | sudo gpg --output /etc/apt/keyrings/rocos.gpg --dearmor

2. Add the repository to apt sources:

   echo "deb [signed-by=/etc/apt/keyrings/rocos.gpg] https://packages.rocos.io/apt stable main" | sudo tee /etc/apt/sources.list.d/rocos.list > /dev/null
   sudo apt update
   tip

   If desired, replace stable with unstable now. See warning below.

Install the Package

Latest Version

sudo apt update && sudo apt install rocos-agent -y

Specific Version

sudo apt update && sudo apt install rocos-agent=1.6.10-54673 -y

Upgrade the Package

1. Upgrade the package with apt:

   sudo apt update && sudo apt install --only-upgrade rocos-agent

2. Restart the agent service:

   sudo systemctl restart rocos-agent
   info

   Upgrading the agent will NOT stop the current running agent, in order to allow upgrading the agent remotely. Therefore, it is require to restart the agent service manually following the package upgrade.

Switch to the Unstable Channel

warning

The unstable version of the agent includes newer features and improvements, but has not been as thoroughly tested as a stable release. It may have bugs or unexpected changes in functionality. We recommend that you test the unstable build to validate correct operation for your specific use case before using it in a production environment. Most users are recommended to use the stable version unless they require functionality in the unstable build.

1. Configure apt sources:

   echo "deb [signed-by=/etc/apt/keyrings/rocos.gpg] https://packages.rocos.io/apt unstable main" | sudo tee /etc/apt/sources.list.d/rocos.list > /dev/null
   sudo apt update

2. Upgrade the package (see above)

Remove the Package

1. Remove the package with apt:

   sudo apt remove rocos-agent
   info

   This will keep the configuration files on the host. To completely remove any trace of the agent, including the configuration files run purge instead:

   sudo apt purge rocos-agent

2. Remove source list and keyring:

   sudo rm /etc/apt/sources.list.d/rocos.list
   sudo rm /etc/apt/keyrings/rocos.gpg

Initialize the Agent

The first time you start the agent, the agent will start interactively, and ask you a series of questions in order to configure the agent for your robot:

sudo rocos-agent

1. First you will need to login. The agent will display a link: you will need to click on the link shown, then log into the DroneDeploy Robotics Portal in your browser. You will then be provided a code which you will need to paste back into the terminal in order to authenticate the agent.
2. Then pick the Project which you'd like to connect this robot to. If you only have one Project in your account, then this step will be skipped. If you have not created a Project yet, this step will fail: in which case go and create one on the DroneDeploy Robotics Portal, then re-run sudo rocos-agent)
3. You'll now be asked to choose a callsign. Callsigns must be unique within your Project, be lower case and only contain alphanumeric characters or hyphens. An example of a valid callsign is robot-1. Note you won't be able to change the callsign once you've created the robot, so choose wisely.
4. You can now choose a friendly name for the robot; this does not have the same character restrictions as the callsign, so you can be more descriptive here.
5. Once this is all done you can now click on the provided link to be taken to your robot's new dashboard page in the DroneDeploy Robotics Portal.
6. After completing the initialization, the Agent will exit; at this point, you can start the background service manually - it will then continue to start automatically the next time the robot boots up:

sudo systemctl start rocos-agent

Your robot should now appear online in the DroneDeploy Robotics Portal.

Configuring the Agent

The agent attempts to select the most appropriate behavior for your robot automatically, however some manual configuration may be required, for instance - to set the appropriate paths to find custom files and port numbers at which to connect to other system services.

For most systems, the agent configuration is managed remotely via the DroneDeploy Robotics Portal. Refer to the Remote Configuration documentation.

For robots operating in an offline environment, the configuration of the agent should be managed by editing of the local configuration file /etc/opt/rocos-agent/components.json.

See each plugin's documentation for more information about what you can change, for example, checkout the ROS Plugin.

Reinitializing the Agent

If you need to reinitialize the robot (for example, because you want to change which project it is connected to in the DroneDeploy Robotics Portal) you can run:

sudo rocos-agent --init

This will reset the authentication details and allow you to reinitialize the robot from the start.

Run the Agent

By default, the installer will configure the to agent run in the background as a service/daemon, which runs as its own dedicated "rocos-agent" user:

When the installer detects that your system is using Upstart as the init manager (namely, that's Ubuntu 14.04), an Upstart job is created at /etc/init/rocos-agent.conf.

When the install detects that your system is using systemd as the init manager (Ubuntu 16.04 and onwards), a systemd service definition is created at /lib/systemd/system/rocos-agent.service and enabled.

The installer will set up the service, but not actually start the service running: this is because the first time you will run the agent interactively in order to authenticate. The service will run automatically the next time the system starts up.

Running the Agent in the Foreground

If you do not want the agent to run automatically as a service, then you will need to disable the service after installation (but before rebooting or manually starting the service).

On systems using Upstart as init manager (Ubuntu 14.04), you should create an override file:

echo manual | sudo tee /etc/init/rocos-agent.override

On systems using systemd as init manager (Ubuntu 16.04+), you should mask the service:

sudo systemctl mask rocos-agent

There are other methods of disabling the service; the above approach has the advantage that the service will remain disabled permanently, even after the agent package is updated.

With the service disabled, you will need to run the agent binary manually (note to run it as the rocos-agent user to avoid permissions issues if you later want to run the agent as a service):

sudo -u rocos-agent rocos-agent -d

Special Environment Variables

On some robots, the default environment may interfere with the ability of the Agent software to operate normally: for instance, if the Agent executable is not able to access the internet without going via a proxy server. In this case, you may need to provide some additional configuration settings to the agent by way of environment variables.

Environment variables can be provided to the agent through use of a custom service configuration. See the following instructions, which illustrate creating an environment variable named NAME with value "value":

On systems using Upstart as init manager (Ubuntu 14.04), you should create an override file:

sudo cp /etc/init/rocos-agent.conf /etc/init/rocos-agent.override

Edit this file using your preferred text editor, and add lines with the following form at the bottom of the file:

env NAME=value

On systems using systemd as init manager (Ubuntu 16.04+), you should create a user service file:

sudo cp /lib/systemd/system/rocos-agent.service /etc/systemd/system/rocos-agent.service

danger

If the agent service is masked using systemctl as described above in the instructions in Running the Agent in the Foreground, the user service file created will be deleted.

Edit this file using your preferred text editor, and add lines with the following form at the bottom of the file:

Environment=NAME=value

In the case of operation via a proxy server, the environment variables you probably want to set are:

env http_proxy=001.002.003.004:9999 # This should be the address and port of your proxy server.
env no_proxy=127.0.0.1,011.022.033.044,111.222.333.444 # This should list IPs of anything the agent might need to talk to that does _not_ require going through the proxy.