LinuxCommandLibrary

pio-remote

Control PlatformIO projects on remote machines

TLDR

List all active Remote Agents

$ pio remote agent list
copy

Start a new Remote Agent with a specific name and share it with friends
$ pio remote agent start [[-n|--name]] [agent_name] [[-s|--share]] [example1@example.com] [[-s|--share]] [example2@example.com]
copy

List devices from specified Agents (omit --agent to specify all Agents)
$ pio remote --agent [agent_name1] --agent [agent_name2] device list
copy

Connect to the serial port of a remote device
$ pio remote --agent [agent_name] device monitor
copy

Run all targets on a specified Agent
$ pio remote --agent [agent_name] run
copy

Update installed core packages, development platforms and global libraries on a specific Agent
$ pio remote --agent [agent_name] update
copy

Run all tests in all environments on a specific Agent
$ pio remote --agent [agent_name] test
copy

SYNOPSIS

pio-remote [options]

PARAMETERS

agent
    Controls the PlatformIO Remote Agent.

agent run
    Starts the PlatformIO Remote Agent on the remote machine. Note: the agent requires the `pio account` to be logged-in on the remote side. The remote agent allows you to connect to remote PlatformIO projects and execute remote commands.

agent stop
    Stops the PlatformIO Remote Agent on the remote machine.

run
    Executes a PlatformIO command on a remote machine. Requires a configured remote environment (e.g., via SSH).

run --project-dir
    Specifies the project directory on the remote machine.

run --command
    Specifies the PlatformIO command to execute on the remote machine (e.g., `build`, `upload`).

--target
    The target build environment name.

--environment
    The project environment(s) name.

--upload-port
    Upload port PORT.

--upload-protocol
    Upload protocol PROTOCOL.

--monitor-port
    Monitor port PORT.

--monitor-speed
    Monitor speed SPEED.

version
    Shows the version of PlatformIO Remote.

DESCRIPTION

The `pio-remote` command is a utility provided by the PlatformIO ecosystem that facilitates remote development workflows. It enables users to connect to and manage PlatformIO projects on remote machines (e.g., servers, virtual machines, or embedded devices). This allows developers to leverage resources, test on different architectures, or deploy directly to a target platform from their local development environment. The `pio-remote` command typically handles tasks such as: establishing SSH connections, synchronizing project files, executing build commands on the remote host, and providing access to the remote machine's filesystem and console output. It aims to streamline the process of building, testing, and deploying embedded software or IoT applications in scenarios where direct local compilation or deployment is impractical or undesirable. Note: Requires pre-installation and configuration of PlatformIO on both local and remote machines.

CAVEATS

Requires PlatformIO to be installed on both the local and remote machines, and SSH access configured. Firewall rules may need to be adjusted to allow communication between the local and remote systems. Authentication with a valid PlatformIO account is required for remote agent functionality.

CONFIGURATION

The remote environment typically requires SSH key-based authentication for secure access. You'll need to configure the `platformio.ini` file to specify the remote connection details, including the hostname, username, and path to the project directory on the remote machine.
Example:
```ini
[env:remote_build]
platform = native
extra_scripts =
pre:remote_build.py

[remote]
host = user@remote_server.com
project_dir = /path/to/remote/project
```

TROUBLESHOOTING

Common issues include SSH connection errors, incorrect project directory paths, and firewall restrictions. Verify SSH connectivity, double-check the configuration file, and ensure that the necessary ports are open on both the local and remote firewalls.

HISTORY

The `pio-remote` command was introduced as part of the PlatformIO ecosystem to address the growing need for remote development capabilities in embedded systems and IoT projects. Its development was driven by the need to efficiently manage projects on remote hardware and to enable collaborative development across geographically distributed teams. It has evolved to support various remote access methods, including SSH, and has integrated with PlatformIO's build and deployment workflows.

SEE ALSO

ssh(1), pio(1)

Copied to clipboard