Remotely control Linux Raspberry Pi from Windows PowerShell.

Porthole cmdlet for PowerShell provides all the functionality that a user has when using the graphical or CLI interface to Porthole.

Common tasks:

Automate scripts against a device or devices
Open a terminal from Windows PowerShell
Manage local portforwarding routes to remote devices
Query device status

For the impatient, here is the basic concept:

# Connect the local instance of Porthole to your Dataplicity account
PS > Register-Porthole
Login: <email>
Password: **************
Logging in...
Name             Email
- ---             - ----
Terry Pratchett  <email>

# Reboot a Raspberry Pi remotely
PS > Restart-PortholeDevice -Device 12345678-1234-1234-1234-123456789000
Rebooting device...
True

# Run a command on a Raspberry Pi remotely and get the result
PS > Invoke-PortholeCommand -Device 12345678-1234-1234-1234-123456789000 ^
                            "cat /proc/cpuinfo| grep Hardware"
StandardOutput
- -------------
Hardware        : BCM283...

# Forward port SSH (22) on a remote device to port 1022 on your local PC
PS> Add-PortholeForward -Device 12345678-1234-1234-1234-123456789000 ^ 
                        -LocalPort 1022 -RemotePort 22
Creating new forward...

DeviceName  : Boxy McBoxface
LocalPort   : 1022
RemotePort  : 22
IsLocalOnly : True
DeviceId    : 12345678-1234-1234-1234-123456789000

# Now you can SSH to your remote device by pointing # your favourite SSH 
# client to port 127.0.0.1:1022.

Getting Started

To start using cmdlet commands, you need to import them first. Open PowerShell, change your directory to that one where your Porthole is installed, and next run:

PS D:\Porthole> Import-Module '.\Dataplicity Porthole.dll'

Now your cmdlet porthole commands are imported, you can freely use them.

Device management

Get-PortholeDevices

Returns a list of all available devices.

Syntax

Get-PortholeDevices

Example usage

PS> Get-PortholeDevices
Checking devices...

DeviceName   : Boxy McBoxface
DeviceId     : 12345678-1234-1234-1234-123456789000
DeviceStatus : Online
MachineType  : Raspberry Pi 3 Model B
AgentVersion : 0.4.29

DeviceName   : debian1
DeviceId     : 12345678-1234-1234-1234-123456789001
DeviceStatus : Offline
MachineType  : Other linux device
AgentVersion : 0.4.29

DeviceName   : demo1
DeviceId     : 12345678-1234-1234-1234-123456789002
DeviceStatus : Online
MachineType  : Other linux device
AgentVersion : 0.4.27a2

Outputs

Parameter	Description
Device name	User specified device name as defined in the attached Dataplicity account.
Device	Unique Device API ID for the device.
Machine type	Friendly description of device type. Examples include: "Raspberry Pi Model Compute Module" "Raspberry Pi Model B+" "Other linux device"
Status	"Online" if a device is connected to Dataplicity at the present moment. "Offline" otherwise.
Agent version	Dataplicity Agent version reported by this device. Example: 0.4.29

Get-PortholeDeviceStatus

Query the online status of all registered devices.

The "Device" parameter may be used to filter the search to a particular device.
Syntax

Get-PortholeDeviceStatus [-Device <String>]

Example usage

PS> Get-PortholeDeviceStatus
Checking devices...

DeviceName                 DeviceId                             DeviceStatus
- ---------                 - -------                             - -----------
Boxy McBoxface             12345678-1234-1234-1234-123456789000 Online
debian1                    12345678-1234-1234-1234-123456789001 Offline
demo1                      12345678-1234-1234-1234-123456789002 Online

Outputs

Parameter	Description
Device name	User specified device name as defined in the attached Dataplicity account.
Device	Unique Device API ID for the device.
Status	"Online" if a device is connected to Dataplicity at the present moment. "Offline" otherwise.

Invoke-PortholeCommand

Remotely execute a command against a device.

Syntax

Invoke-PortholeCommand -Device <String> -Command <String>

Inputs

Parameter	Description
Device	Unique Device API ID for the device.
Command	Remote command to execute. Example: "cat /proc/cpuinfo"

Example usage

PS > Invoke-PortholeCommand -Device 12345678-1234-1234-1234-123456789000 ^
                            "cat /proc/cpuinfo| grep Hardware"
StandardOutput
- -------------
Hardware        : BCM283...

Outputs

Parameter	Description
Device name	User specified device name as defined in the attached Dataplicity account.
Device	Unique Device API ID for the device.
Status	"Online" if a device is connected to Dataplicity at the present moment. "Offline" otherwise.

Invoke-PortholeDeviceTerminal

Opens an "SSH-like" terminal to a remote device from the PowerShell command prompt.

Syntax

Invoke-PortholeDeviceTerminal-Device <String>

Inputs

Parameter	Description
Device	Unique Device API ID for the device.

Example usage

PS> Invoke-PortholeDeviceTerminal -Device 12345678-1234-1234-1234-123456789000

Restart-PortholeDevice

Remotely reboot a device.

Syntax

Restart-PortholeDevice -Device <String>

Inputs

Parameter	Description
Device	Unique Device API ID for the device.

Example usage

PS> Restart-PortholeDevice-Device 12345678-1234-1234-1234-123456789000
Rebooting device...
True

Session management

Get-PortholeProfile

Returns the username for the currently attached Dataplicity account.

Syntax

Get-PortholeProfile

Example usage

PS> Get-PortholeProfile
Getting profile...
Name             Email
- ---             - ----
Terry Pratchett  <email>

Outputs

Parameter	Description
Username	Username of the Dataplicity account attached to the local instance of Porthole.

Register-Porthole

Attaches the local instance of Porthole to a Dataplicity account.

This command does not accept parameters but will instead prompt for username, password, and two-factor security code (if required).

Syntax

Register-Porthole

Example usage

PS> Register-Porthole
Login: <email>
Password: **************
Logging in...
Name             Email
- ---             - ----
Terry Pratchett  <email>

Update-PortholeToken

Updates the authorisation token used by the local instance of Porthole.

This function is probably not required if you are using Register-Porthole to request a Token with a username and password, but could be useful in production applications.

Syntax

Update-PortholeToken -Token <String>

Example usage

PS> Update-PortholeToken -Token <token>
Login: <email>
Password: **************
Logging in...
Name             Email
- ---             - ----
Terry Pratchett  <email>

Unregister-Porthole

Detaches the local instance of Porthole from Dataplicity. The Porthole system service will be restarted and all open routes will be terminated.

Syntax

Unregister-Porthole

Example usage

PS> Unregister-Porthole
Are you sure you want to log out? [yes/no] [y/n]
y
Logging out...
Logged out successfully.

Port forwarding configuration

Add-PortholeForward

Inserts a new port forwarding entry to redirect a TCP port on a Dataplicity-enabled remote device to localhost.

Syntax

Add-PortholeForward -Device <String> -LocalPort <int> -RemotePort <int> [-IsLocalOnly <bool>]

Inputs

Parameter	Description
Device name	User specified device name as defined in the attached Dataplicity account.
Local port	Local TCP port which is listening for connections to forward to the remote host.
Is local only	"Yes" if the local port is available to localhost only. "No" if the local port is listening on all local interfaces (and therefore is accessible from the local network).
Device	Unique Device API ID for the device.
Remote port	Remote TCP port where socket traffic on the local TCP port is to be redirected. Commonly '22' for SSH, '5901' for VNC.

Example usage

PS> Add-PortholeForward -Device 12345678-1234-1234-1234-123456789000 -LocalPort 1022 -RemotePort 22
Creating new forward...

DeviceName  : Boxy McBoxface
LocalPort   : 1022
RemotePort  : 22
IsLocalOnly : True
DeviceId    : 12345678-1234-1234-1234-123456789000

Get-PortholeForwards

Returns a list of all port forwards configured in the local instance of Porthole.

Syntax

Get-PortholeForwards

Example usage

PS> Get-PortholeForwards
DeviceName  : Boxy McBoxface
LocalPort   : 1022
RemotePort  : 22
IsLocalOnly : True
DeviceId    : 12345678-1234-1234-1234-123456789000

Outputs

Parameter	Description
Device name	User specified device name as defined in the attached Dataplicity account.
Local port	Local TCP port which is listening for connections to forward to the remote host.
Is local only	"Yes" if the local port is available to localhost only. "No" if the local port is listening on all local interfaces (and therefore is accessible from the local network).
Device	Unique Device API ID for the device.
Remote port	Remote TCP port where socket traffic on the local TCP port is to be redirected. Commonly '22' for SSH, '5901' for VNC.

Remove-PortholeForward

Removes a existing port forwarding entry from the local instance of Porthole.

Syntax

Remove-PortholeForward -LocalPort <int>

Inputs

Parameter	Description
Local port	Local TCP port which is listening for connections to forward to the remote host.

Example usage

PS> Remove-PortholeForward -LocalPort 1022
RemovedForwardsCount
- -------------------
                   1