GuidesAPI Reference
API Reference

Agent local files

FreedomRobotics Agent locally installed files

FreedomRobotics local files

When installing FreedomRobotics Agent, some new files will be installed on to your system.

Python module files

The freedomrobotics module is installed by default using pip with --user option, placing the files inside ~/.local/lib/pythonx.y/site-packages. If the installer detects there is an activated virtualenv or anaconda environment, the module files will be correctly placed in it.
The dependencies that are not satisfied before installation will be installed in the same place.

Base PATH

Besides the module files, the Agent installation script creates a freedomrobotics directory where
the configuration of the agent, agent logs, upgrade logs, error reports and others will be stored.

By default the base location is ~/.config/freedomrobotics

Credentials file

This file is the most important one of them all.
It contains all the details needed to connect to the API and settings for Link and/or Agent.

Content example for the credentials file: 

{
    "url": "https://api.freedomrobotics.ai/",
    "account": "A1234567890ABCDEF1234567890",
    "device": "D1234567890ABCDEF1234567890AB",
    "token": "T1234567890ABCDEF12345678",
    "secret": "S1234567890ABCDEF12345678",
    "code_branch": "release",
    "install_elements": [
        "warn_no_fail",
        "webrtc"
    ],
    "configuration": {
        "measurements": {
            "disabled": [],
            "enabled": [
                "resources",
                "platform",
                "ros",
                "processes",
                "network",
                "webrtc",
                "gpu"
            ]
        },
        "webrtc_local_port": 5540
    },
    "log_level": "INFO"
}

Attributes explained:

  • url - the base url for freedomrobotics api endpoints
  • account - the id of your freedomrobotics account
  • device - the id of the current device
  • token and secret - the credentials specific for the current device, used to authenticate on the API side
  • code_branch - the branch from which the agent was installed from (historical value)
  • install_elements - the list of elements used at install time;
    it allows the freedomrobotics code know which features can or can not be used
    (feature dependencies are not installed), and how was the module installed.
    All possible install elements: webrtc, service_systemd or service_initd or service_none,
    ros1 or ros2 or no_ros, no_credentials, no_ssh, no_rollback, verbose, warn_no_fail.
  • configuration - a json dict of settings for Agent and Link. Supported attributes:
    • webrtc_local_port - the port number to be used for communicating between Link and WebRTC local processes
      (internal port listening on local interface only - 127.0.0.1).
    • measurements - a json dict for configuring what measurements should the Agent collect and what not.
      It expects 2 lists under enabled and disabled keys. If a measurement is mentioned in both lists,
      it will be disabled, and if it is not mentioned in any of the lists, it will be enabled.
      All supported measurements elements (to be specified in one of the lists):
      • resources - for cpu usage, cpu temperature, virtual memory usage, swap usage, disk space usage
      • platform - for collecting various details specific to the system/platform, like: CPU architecture,
        OS (type, distribution name, version, upgradable packages),
        python (version/implementation/build/compiler).
      • ros - for ros version, list of nodes, and running state
      • processes- for getting a list of the running processes (having a significant cpu or memory usage)
        with details including: cpu usage, memory usage, process id, process name, user
      • network - for network interfaces, details include: ping stats, local and public IP addresses,
        RX/TX stats (data size, number of packets, errors, dropped packets),
        WIFI connections stats (ESSID, link quality, rate, signal level, number errors, etc)
      • webrtc - for WebRTC stats like: connection state, data/video bytes rate, latency,
        last received command/ping time, video max width/high/FPS, etc
      • gpu for GPU usage, temperature, memory
  • log_level - the desired log level. Possible values: DEBUG, INFO, WARNNING, ERROR, FATAL.

This file is usually created at install time by the installation process (automatically generated).
If sore some reason, the agent is installed without these credentials file (having no_credentials in
install_elements list), make sure you prepare the file with valid content before starting Agent or initializing Link.

Lock files

Each Link instance and Agent will create a lock file inside the base path.
These lock files are used to control the lifecycle of the Link/Agent instances, for example if a new Agent is started,
agent.lock will be replaced and the old agent process will stop detecting the lock is different.

Note that Link/Agent will shut down if its specific lock file is removed or replaced.

Log files

Inside the base path, you should be able to find a logs folder which is created at install time.
Inside it you can find log files like:

  • agent.log - containing agent logs (if there are issue with the service, this is the place to look first).
  • agent_link.log - containing logs from the Link instance started by the agent to upload messages to the API.
  • webrtc_sync.log - containing logs from the Link instance in regard to WebRTC commands and signals.
  • webrtc_async.log - containing logs from the WebRTC python3 process which does the actual RTC connection.
  • link_ros.log or link_ros2.log - containing logs from the LinkRos or LinkRos2 instance started by the agent,
    depending on detected ros distribution on the system.

These are the main default log files, but you could have others in case you instantiate Link objects for custom use;
for example, if you initialize like with Link('link_core'), the logs from this instance will be saved in link_core.log.

Beside these log files, you could find log files containing a timestamp in the name and even archived files.
In order not to use a lot of disk space, logs are rotate, archived and oldest ones removed.
By default a rotation will happen when the log file is larger than 30M. The log file content will be moved to a new file
which contains an extra timestamp in its name, and then if older timestamped log files exist for the same log,
they will be archived using gzip. If there are more than 9 archives for a log, the older ones will be removed,
keeping only the last 9. Example set of rotated logs: agent.log, agent_20201014_182311.log, agent_20201012_161345.log.gz
agent_20201010_120339.log.gz

Installation logs

The logs/install folder stores the FreedomRobotics Agent installer script logs from each installation attempt.

Errors

The logs/errors folder contains a json files (timestamp included in their name) for each individual
crash/error that happened in Agent or Link code.

Service files

Depending on your system type, one of the next files group bellow will be added to /etc/:

  • /etc/init.d/freedomrobotics

or:

  • /etc/systemd/system/freedomrobotics.environment
  • /etc/systemd/system/freedomrobotics.service

Service freedomrobotics will be configured to automatically start on reboot and in case of crashes (systemd only).