Some drivers expose binary data streams in addition to discrete addresses — typically file transfer protocols (FTP, S-Bus block reads, OPC UA file objects, …). The /peers/{driver}/{id}/streaming endpoint exposes these streams over plain HTTP, so any client can upload or download a file without learning the driver's wire protocol.
This endpoint maps directly onto two driver methods:
readStream(address, socketName, options, callback) — invoked by GETwriteStream(address, socketName, options, callback) — invoked by POSTDrivers that do not implement these methods return 500 when called.
GET /peers/{driverType}/{gatewayId}/streaming?address={addr}&fileName={name}&options={json}
POST /peers/{driverType}/{gatewayId}/streaming?address={addr}&fileName={name}&options={json}
| Segment | Description |
|---|---|
driverType |
Driver name (e.g. ftp, saia, opcua) |
gatewayId |
Numeric id of a configured gateway instance of that driver |
| Query parameter | Description |
|---|---|
address |
The address (or path) to read from / write to on the driver — semantics depend on the driver |
fileName |
Optional. Filename advertised in the Content-Disposition header on download. Defaults to fileName |
options |
Optional. JSON-encoded object passed verbatim to the driver. Driver-specific |
GET)The gateway opens a stream to the driver, sets the appropriate headers, and pipes the bytes directly to the response.
Response headers:
Content-Disposition: attachment; filename=<fileName>
Content-Type: application/octet-stream
Content-Length: <size, when the driver knows it in advance>
If the driver knows the file size up front, it is sent as Content-Length. Otherwise the response uses chunked transfer encoding and ends when the driver closes the stream.
Example — download a file from an FTP gateway:
curl -b cookies.txt -OJ \
'https://gateway.example.com/peers/ftp/3/streaming?address=/exports/report.csv&fileName=report.csv'
The -OJ flags tell curl to use the filename from the Content-Disposition header.
Example — pipe directly into another tool:
curl -b cookies.txt -s \
'https://gateway.example.com/peers/ftp/3/streaming?address=/data/dump.bin' \
| gzip > dump.bin.gz
POST)POST to the same URL with the file as the request body. The gateway opens a write stream on the driver and pipes the request body straight through.
Request:
POST /peers/ftp/3/streaming?address=/uploads/firmware.bin
Content-Type: application/octet-stream
Content-Length: 1048576
<raw bytes>
The Content-Length header is forwarded to the driver as the bytes field of options, which lets some drivers preallocate or display upload progress.
Response:
200 OK with no body on success, 500 with {"err":"..."} on failure.
Example — upload a firmware blob to a SAIA gateway:
curl -b cookies.txt -X POST \
-H 'Content-Type: application/octet-stream' \
--data-binary @firmware.bin \
'https://gateway.example.com/peers/saia/7/streaming?address=/firmware'
The options query parameter accepts any JSON-encoded object that the driver knows how to interpret. There is no fixed schema — each driver documents its own options. Common keys you may encounter:
| Key | Description |
|---|---|
bytes |
File size in bytes (auto-set from Content-Length on POST) |
offset |
Resume offset for partial downloads / uploads |
mode |
Transfer mode (e.g. binary, ascii on FTP) |
chunkSize |
Block size for chunked drivers |
To pass options:
?options=%7B%22mode%22%3A%22binary%22%2C%22offset%22%3A0%7D
(URL-encoded {"mode":"binary","offset":0})
Stream errors are reported as a 500 response with a JSON body when the connection allows it:
{ "err" : "driver disconnected" }
For partial transfers (the connection was already streaming when the error happened), the gateway closes the stream early. Clients should treat a truncated download as a failure unless they have an out-of-band way to verify integrity (size, checksum).
The /peers/* dispatcher is designed for discrete RPC calls with JSON arguments and JSON responses — it does not handle binary payloads efficiently. The /streaming endpoint exists specifically for binary data:
| Use case | Best choice |
|---|---|
| Read/write a value | /peers/{peer}/{module}/{method} |
| Transfer a file or large binary blob | /peers/{driver}/{id}/streaming |
| Retrieve driver diagnostic logs | /peers/{driver}/{id}/logs_* |