Installer Configuration

Here we describe the options available on when running your Heex Agent.

​

Installer options

The user has the possibility to add some instructions as stated in the following table. Here is how you do it.

./Agent_<version>_Ubuntu_20.04_x86_64_installer -- --option1 argument --option2 argument2

​

Heex Agent runtime configuration (-m)

Check kernel configuration for more information.

​

Deployment execution mode (-x)

The user can chose to either launch them as services or background processes since sometimes launching services is not possible (ie in docker environments). This choice is done via the --execution (or -x) command, added with either service or background as an argument. Please understand that when in background process mode, any system reboot will not automatically re-run the Heex Agent. Example:

./Agent_<version>_Ubuntu_20.04_x86_64_ES-XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX_installer -- -x background

​

Uninstallation (-u)

If you want to remove the running services (or background processes) and all the created folders, you can simply call the installer with the --uninstall option and it’ll proceed to do so, no other input needed.

​

Adding custom files

If for any reason you wish to include custom files/folders of any type, we have added a dedicated space for them: the additionalAgentContent folder, which is located at the root of your SDK folder. Any file or folder you add inside it will be copied into the Heex Agent with the same arborescence (they shall be copied inside <Agent_root>/additionalAgentContent/).

​

Agent’s Header and Footer files

We’ve enhanced the flexibility of our installer by introducing the capability for users to run custom code before the Heex Agent launch. To avail of this feature, prior to create your installer, you create either or both of the following files within the additionalAgentContent folder:

• additionalAgentContent/agentSetupHeader.sh: The code added inside this file will be run (sourced) before any of the Agent implementations are started
• additionalAgentContent/AgentSetupFooter.sh: The code added inside this file will be run (sourced) after any of the Agent implementations are started

In addition to this, we have also added the possibility for the user to source files inside the Linux services in which the implementations will be ran. To do so, please refer to the following paragraph

​

Linux additional environment setup

Since the installation is done inside user services, which runs in contained environments, user environment variables need additional tweaking to be applied. At installation, we shall, by default, include all environment variables available at installation into the service environment. This can be disabled though, if you set the variable DISABLE_SOURCING_OF_LOCAL_ENVIRONMENT to 1.

​

Sourcing custom files

To source custom files into the Heex Agent environment, you have 2 options:

• List them into your additionalAgentContent/agentSetupHeader.sh file:
  You can source additional files before the executables are ran. You need to add their full paths in the bash array typed variable named FILES_TO_SOURCE_IN_HEEX_AGENT_ENV inside the additionalAgentContent/agentSetupHeader.sh script.

  ⚠️ Warning:

  It is recommended to use full paths. The character ~ won’t always correctly reference paths to your HOME directory.

  📝 Note:

  If you mean to source several files, know that the order of the declaration of each file in the list is the order in which we source the files.

• Use /opt/heex/defaultAgentSourcing.sh file: see description below

​

Sourcing custom variables

You can also export variables into the services or background processes. To do so, you have 2 options:

• You may define new (or update exiting) environment variables inside the VARIABLES_TO_EXPORT_IN_HEEX_AGENT_ENV variable. Please take a look at the Templated header file below for more info.

• Use /opt/heex/defaultAgentSourcing.sh file: see description below

​

Templated header file

The additionalAgentContent/agentSetupHeader.sh is automatically generated and added into the packaged SDK, but if the file is not present, you can create it yourself at the root of the package, and paste the following inside it:

#!/bin/bash
##################################################################
## specific files to source in the Heex Agent bash environments ##
##################################################################

## Replace the commented lines in the following FILES_TO_SOURCE_IN_HEEX_AGENT_ENV variable to source
## specific files inside the Heex Agent environment before they are launched. Please ensure that
## the paths are full paths without any '~' in them.
## NOTE: THE SOURCING OF THE FILES IS DONE IN THE ORDER OF DECLARATION!

FILES_TO_SOURCE_IN_HEEX_AGENT_ENV=(
#    "path/to/file1.sh"
#    "path/to/file2.bash"
#    ...
) # it needs to be kept as a list

##################################################################
########### specific Heex Agent installer variables ##############
##################################################################

## Following variable is for ROS environment only. If you set this to 1, the Heex Agent
## Installer shall not look for any installed ROS distribution inside the /opt/ros folder and
## will not source them in the Heex Agent environment. By doing so, you will need to explicitly
## add the path to your ROS distribution's installation inside the FILES_TO_SOURCE_IN_HEEX_AGENT_ENV
## variable mentionned above.

DISABLE_AUTOMATIC_ROS_INSTALL_SEARCH=0

## By default, when you install our Heex Agent, we include all user's environment variables available. 
## If you set the following variable to 1, we will not include them and leave it to the system env only.
## NOTE: if you run in background process, the env is not contained so the user's env is automatically sourced

DISABLE_SOURCING_OF_LOCAL_ENVIRONMENT=0

## Whether you disable the local environment sourcing or not, you may want to add environment variables
## into the Heex Agent's environement. You may add any variable in the following list. Please make sure
## you follow the 'env="value"' format as shown below.

VARIABLES_TO_EXPORT_IN_HEEX_AGENT_ENV=(
    'HEEX_AGENT_ENV_VAR="VALUE1"'
    'ANOTHER_ENV_VAR=123456'
) # it needs to be kept as a list

##################################################################
##################################################################

​

ROS2 specific configuration

In the template written above, you might notice an additionnal variable defined in it: DISABLE_AUTOMATIC_ROS_INSTALL_SEARCH. If you do not work with ROS2, you can ignore it. If you do, feel free to check out the specific ROS2 configuration page

​

/opt/heex/defaultAgentSourcing.sh specific case

At every installation, our Heex Agent shall look for a file, /opt/heex/defaultAgentSourcing.sh, and if it exists, it’ll source it inside its environment. So on any system you want, you can create this file at this exact location, and inside it you can source any files you want sourced into the Heex Agent env, or export any environment variables you’d want to have added.

An example of the /opt/heex/defaultAgentSourcing.sh file could be:

source /opt/ros/custom/MyCustomMsg/setup.bash
export CUSTOM_ENV_VARIABLE="myVar"
source /some/other/file.sh
export OTHER_CUSTOM_ENV_VARIABLE=123456