Define Edge Agent /Device Interface

[sammachin]

Description

Define the interface that the Edge Agents(#447) connect to in order to register as Devices(#446)

Epic/Story

No response

[knolleary]

The proper solution here will be via a Message Broker service that we host as part of the platform. This will allow secure 2-way communication and will also be usable for data flows from the Edge hosted projects to projects in the cloud platform.

For MVP we can make use of an HTTP based solution. But we must acknowledge this will not satisfy later requirements beyond the MVP.

1. HTTP - easiest to add to our existing platform, but will require the devices to poll for updates. That will mean a delay between a user wanting to send a command to a device, and the device polling the platform to receive it. This will not be a long term solution
2. WebSocket - this will allow for a bi-direction, more responsive communication. But they can be problematic over remote connections - particular when crossing corporate network boundaries (or is that an outdated view?) Also less clear in terms of scalability on the server side - how many concurrent WS connections can we sustain?

Assuming a pure HTTP approach, for this specific task - defining the API will happen in parallel to developing the core edge agent, so its hard to size it as a specific task.

[PLCMercenary]

It seems to me, - and I am quite likely to be completely wrong here, that an HTTP endpoint as a back end isn't valuable iteratively if its effort that is ultimately not going to be in use. In my imagined implementation of a back end is a broker on the edge runtime and a service from the forge that can command the edge in specific ways. or a pair of brokers one baked in the forge, and a broker in each edge runtime with services and events defined at each end

[knolleary]

I agree that a broker based approach is the right technical approach and where we need to end up - as I said in my previous comment.

An initial HTTP based approach is valuable as it allows us to build a working end-to-end solution much quicker to begin validating the concepts with real users.

At this point, we're doing the planning work to see what it takes to get to that MVP and trying to balance the competing demands of keeping moving towards the desired technical goal, and delivering value regularly. We will need to plan for work on the broker approach as that will be a prerequisite for later items.

[sammachin]

I dont' think websockets are problematic these days, again considering this is MVP we likely won't support edge devices behind corporate proxies anyway.

The Node-RED editor already uses a websocket too so if people are still in some kind of environment that makes those connections difficult to flowforge they will have bigger issues

[knolleary]

The following API is for the 0.6 MVP. It is a polling based API - which is not ideal and not the long term solution. It is, however, a starting point to get something working in the 0.6 time frame.

Edge Agent Configuration

With the 0.5 work, when a device is registered on the platform, we provide a one-click download of a configuration file for the device. That current includes deviceId and token.

That should be extended to include the forgeURL - the base URL of the platform.

The user should be able to drop that file onto the edge device to a well-known location and not provide any other configuration.

Forge APIs

The following APIs should only be accessible to request that include a valid device
token.

PUT /api/v1/devices/:deviceId/live/state

Called at regular intervals by the Edge Agent, this is how the agent reports its state to the platform.

The payload should look like:

{
   "snapshot": <snapshotIdh>,
   "state": "running|stopped|..."
   ...
}

The response from the platform will be:

• 200 - {status: "okay"} - All is well
• 409 - {status: "incorrect-snapshot", snapshot: <snapshotId>} - the device needs to resync its status with the platform.

GET /api/v1/devices/:deviceId/live/snapshot

Gets the current snapshot the device should be running.

[knolleary]

I've updated the comment above to properly document the API we have in 0.6.

There's no further work to be done on this iteration of the API. We will want to revisit it once we have MQTT/WebSockets/SSE messaging in place - but we can close this story.