pio-remote
Control PlatformIO projects on remote machines
TLDR
List all active Remote Agents
Start a new Remote Agent with a specific name and share it with friends
List devices from specified Agents (omit --agent to specify all Agents)
Connect to the serial port of a remote device
Run all targets on a specified Agent
Update installed core packages, development platforms and global libraries on a specific Agent
Run all tests in all environments on a specific Agent
SYNOPSIS
pio-remote
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.