# Devices

The FlowForge platform can be used to manage Node-RED instances running on remote Devices. A Device runs a software agent that connects back to the platform to receive updates.

This guide explains how to get starting with the Devices feature.

# Installing the Device Agent

The Device Agent is published to the public npm repository as @flowforge/flowforge-device-agent.

It can be installed as a global npm module. This will ensure the agent command is on the path:

sudo npm install -g @flowforge/flowforge-device-agent

Or you can chose to run the Docker container. When you do, you'll need to mount the device.yaml obtained when Registering the device:

docker run --mount /path/to/device.yml:/opt/flowforge/device.yml -p 1880:1880 flowforge/device-agent:latest

# Configuration

# Working directory

By default the agent uses /opt/flowforge-device or c:\opt\flowforge-device as its working directory. This can be overridden with the -d/--dir option.

The directory must exist and be accessible to the user that will be running the agent.

# Linux

sudo mkdir /opt/flowforge-device
sudo chown -R $USER /opt/flowforge-device

# Windows

mkdir c:\opt\flowforge-device

# Listen Port

By default Node-RED will listen to port 1880. The device agent has a flag to change this behaviour and listen on another port of choosing: -p/--port. This can be useful for custom firewall rules, or when running multiple device agents on the same machine.

flowforge-device-agent --port=1881

# Register the device

To connect a device to the platform, it needs a set of credentials.

There are two types of credentials to choose from:

Device Credentials: for connecting a single device to the platform
Provisioning Credentials: for setting up one or more devices to automatically register themselves on the platform

# Generating "Device Credentials"

for a single device

Go to your teams's Devices page.
Click the Register Device button.
You will be prompted to give the device a name and an optional type. The type field can be used to record additional meta information about the device.
Click Register

Once the device has been registered, you will be shown the Device Credentials dialog. This is the only time the platform will show you this information without resetting it. Make sure to take a copy or use the Download button to save the configuration file locally.

Repeat these steps for each device you want to connect to the platform.

# Generating "Provisioning Credentials"

for automatic registration of one or more devices

Go to your teams's Settings page.
Open the Device tab.
Click the Create Provisioning Token tab.
You will be prompted to give the token a name and to chose what instance, if any, the device should be assigned to.
Click Create

Once the Provisioning Token has been created, you will be shown the Device Provisioning Credentials dialog. This is the only time the platform will show you this information. Make sure to take a copy or use the Download button to save the configuration file locally.

# Connect the device

# Using Device Credentials

Copy the Device Credentials information into a file called device.yml in the devices Working Directory (or whatever is set with the -d option).

The agent can then be started with the command: ^[1]

flowforge-device-agent

You will see the device start and perform a 'call-home' where it connects back to the platform to check what it should be running.

# Using Provisioning Credentials

Copy the Device Provisioning Credentials information into a file called device.yml in the devices Working Directory (or whatever is set with the -d option).

The agent can then be started with the command: ^[1:1]

flowforge-device-agent

You will see the device start and perform a 'call-home' where it connects back to the platform to auto register itself in the team devices. If successful, the real Device Credentials are generated and downloaded to the device. The original Provisioning Credentials will be overwritten meaning subsequent runs will not need to perform the auto registration again.

# Assign the device to a Node-RED instance

The next step is to assign the device to a Node-RED instance.

Go to your teams's Devices page.
Open the dropdown menu to the right of the device you want to assign and select the Add to Application Instance option.
Select the instance in the dialog and click Add to continue.

# Deploying a Node-RED instance to the device

To deploy a Node-RED instance to the device:

Create a snapshot - a point-in-time backup of the Node-RED flows and configuration.
Mark that snapshot as the Device Target snapshot.

This model allows you to develop your flows in FlowForge and only push it out to the registered devices when you're happy with what you've created.

# Editing the Node-RED flows on a device

The device agent does not allow local access to the Node-RED editor. This ensures the device is running the deployed snapshot without modification.

When running on FlowForge Cloud, or a premium licensed FlowForge instance, a device can be placed in Developer Mode that enables remote access to the editor.

This can then be used to develop the flows directly on the device and a new snapshot generated from the device that can be deployed to other devices in the application.

Whilst in Developer Mode the device will not receive new updates from the platform when new snapshots are deployed.

Enabling Developer Mode

Go to your teams's Devices page.
Select the device you want to edit by clicking its name.
Click the "Developer Mode" button to enable developer mode.
Once enabled, a Developer Mode Options panel is shown on the Device overview page.

Accessing the Editor

Once developer mode is enabled, click the Enable button next to the 'Editor Access' option
When the editor is available, the Editor button in the header will become active and will take you to the device editor.

Creating a Device Snapshot

To create an instance snapshot from the device use the Create Snapshot button in the Developer Mode options panel.

You will be prompted to give the snapshot a name and description. See Snapshots for more information about working with snapshots.

# Important Notes

Remote access to the editor required Device Agent v0.8.0 or later.
The device must first have a snapshot applied before editor access is possible.
The device will not receive any updates from the platform while in Developer Mode.
Disabling Developer Mode will cause the device to re-connected to the platform and any change to the target snapshot will cause the device to be updated. This will overwrite any changes made in Developer Mode. Therefore, it is recommended to create a snapshot of the changes before disabling Developer Mode.
The device must be online and connected to the platform to enable "Editor Access".
To minimise server and device resources, it is recommended to disable "Editor Access" when not actively developing flows on a device.

# Remove a device from a Node-RED instance

To remove the device from a Node-RED instance:

Go to your teams's Devices page.
Open the dropdown menu to the right of the device you want to remove and select the Remove from application instance option.
Confirm the action by clicking the Remove option.

The device will stop running the current Node-RED flows. It will then wait until it is assigned to another instance.

# Regenerating credentials

To regenerate device credentials:

Go to your team's or instance's Devices page.
Open the dropdown menu to the right of the device and select the Regenerate credentials option.
You will need to confirm this action as the existing credentials will be immediately revoked. If the device tries to use the old credentials it will fail to connect and will delete its local copy of the snapshot it was running. Click Regenerate credentials to continue.

You will then be shown the Device Credentials dialog again with a new set of credentials to copy or download.

# Deleting a device

To delete a device:

Go to your team's or instance's Devices page.
Open the dropdown menu to the right of the device and select the Delete device option.
Confirm the action by clicking the Delete option.

The next time the device attempts to connect to the platform it will find it is no longer authorised and will stop and delete its local copy of the flows it was running.

# Running with no access to npmjs.org

By default the Device Agent will try and download the correct version of Node-RED and any nodes required to run the Snapshot that is assigned to run on the device.

If the device is being run on an offline network or security policies prevent the Device Agent from connecting to npmjs.org then it can be configured to use a pre-cached set of modules.

You can enable this mode by adding -m to the command line adding moduleCache: true to the device.yml file. This will cause the Device Agent to load the modules from the module_cache directory in the Device Agents Working Directory (or whatever is set with the -d option) (e.g. /opt/flowforge-device/module_cache.).

# Creating a module cache

To create a suitable module cache, you will need to install the modules on a local device with access to npmjs.org, ensuring you use the same OS and Architecture as your target device, and then copy the modules on to your device.

From the Snapshot page, select the snapshot you want to deploy and select the option to download its package.json file.
Place this file in an empty directory on your local device.
Run npm install to install the modules. This will create a node_modules directory.
On your target device, create a directory called module_cache inside the Device Agent Configuration directory.
Copy the node_modules directory from your local device to the target device so that it is under the module_cache directory.

# Running the device agent as a service on a Raspberry Pi

Can can run the device agent as a service, this means it can run in the background and be enabled to automatically start on boot.

# Creating a Service File

The first step is creating the systemd unit file for your service. You can start by creating a new file in the /etc/systemd/system directory with a .service file extension:

sudo nano /etc/systemd/system/flowforge-device-agent.service

The recommended content for the service file can be found here this Github page.

# Starting the service on boot (optional)

If you want Node-RED to run when the device is turned on, or re-booted, you can enable the service to autostart by running the command:

sudo systemctl enable flowforge-device-agent.service

To disable the service, run the command:

sudo systemctl disable flowforge-device-agent.service

# Controlling the service

You can start the service with the command:

sudo systemctl start flowforge-device-agent

You can check the current status with the command:

sudo systemctl status flowforge-device-agent

You can stop your with the command:

sudo systemctl stop flowforge-device-agent

# Troubleshooting

If you have problems with the device agent the first thing to do is to enable the verbose logging mode.

To do this add a -v to the command line. This will present a lot more information about what the agent is doing. It will show that is has connected to the FlowForge instance and every time it checks in, it will also log all the local HTTP requests made when accessing the Node-RED Editor via the FlowForge application.

Starting the agent via the command flowforge-device-agent assumes it was installed as a global npm module and your path is properly configured to pick that up. ↩︎ ↩︎