Skip to main content

Ubuntu

Downloading and Installing the Package​

Stable Build​

The following instructions are for installing the stable build of the DroneDeploy Agent. The stable version of the agent has been tested more thoroughly than the newer unstable version, but may lack some newer features; most users are recommended to use the stable version.

From the command line, enter the following in order:

echo "deb https://packages.rocos.io/apt stable main" | sudo tee /etc/apt/sources.list.d/rocos.list
curl https://packages.rocos.io/apt/docs/key.gpg | sudo apt-key add -
sudo apt-get update && sudo apt-get install rocos-agent -y

This does the following:

  1. Adds the DroneDeploy Robotics package list as a new sources list for APT
  2. Downloads a GPG key that can be used to verify DroneDeploy Robotics packages
  3. Updates the APT database and then installs the DroneDeploy Agent

Unstable Build​

The following instructions are for installing the unstable build of the DroneDeploy Agent.

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.

From the command line, enter the following in order:

echo "deb https://packages.rocos.io/apt unstable main" | sudo tee -a /etc/apt/sources.list.d/rocos.list
curl https://packages.rocos.io/apt/docs/key.gpg | sudo apt-key add -
sudo apt-get update && sudo apt-get install rocos-agent -y

This does the following:

  1. Adds the Unstable DroneDeploy Robotics package list as a new sources list for APT
  2. Downloads a GPG key that can be used to verify DroneDeploy Robotics packages
  3. Updates the APT database and then installs the Unstable DroneDeploy Agent

Upgrading the Agent​

To upgrade the agent from an older version, run the following:

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

Please note that if the agent is running as a service, upgrading the agent will NOT stop the current running agent, in order to allow upgrading the agent remotely. Therefore, you will need to restart the agent service manually:

sudo systemctl restart rocos-agent

Installing a Specific Agent​

To install a specific agent based on its version number:

sudo apt-get update
sudo apt-get install rocos-agent=1.6.10-54673
sudo systemctl restart rocos-agent

This does the following:

  1. Makes sure that the system is up to date.
  2. Installs the particular agent version specified by the build number after the equals sign
  3. Restart the agent to ensure that the specified build starts running

Changing between Stable and Unstable Builds​

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.

Assuming the Agent is already installed from either the stable or unstable build, in order to change to the other build:

  1. Edit the /etc/apt/sources.list.d/rocos.list file:
sudo nano /etc/apt/sources.list.d/rocos.list

The content of the file should look like:

deb https://packages.rocos.io/apt stable main
  1. Change the word stable to unstable (or vice versa).
  2. Save and exit the file.
  3. Upgrade the Agent following the instructions in the section above.

The DroneDeploy Agent Service​

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
Warning

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.

Initialising the DroneDeploy 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 initialisation, 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 DroneDeploy Agent​

The agent attempts to select the most appropriate behaviour 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.

Reinitialising the DroneDeploy Agent​

If you need to reinitialise 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 reinitialise the robot from the start.

Upgrading the DroneDeploy Agent​

We're working hard to pack as many features into the DroneDeploy Robotics Portal as possible. This means the DroneDeploy agent will improve in functionality too. To upgrade the agent, start by updating the apt database, then re-run the installer.

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

The agent will remember your robot authentication details (and offline component configuration) during the update, so you should not need to re-initialize it again.

Warning

The installer process for DroneDeploy Agent v0.1.0 and later are not compatible with that used in older versions of DroneDeploy Agent.

In order to upgrade from an old version of the agent to DroneDeploy Agent v0.1.0 or newer, first remove the Agent, then install the new version of the agent as normal.

Removing the DroneDeploy Agent​

To remove the agent from your system, simply run the following, which will uninstall any services and will delete the agent binaries from your system:

sudo apt-get remove rocos-agent

Configuration files for authentication and offline component configuration will not be deleted, and will be used again if the agent is re-installed. To completely remove any trace of the agent, including the configuration files, you should run:

sudo apt-get purge rocos-agent