DVB Adapters API

The adapter methods read and modify the adapter list of the configuration, start, stop and restart adapters, report their signal statistics and list the DVB devices of the host. Most of them are served on the POST /control/ entry point with the command name in cmd; the info method is served on the path entry point, the status method on both. See How to call API methods for the entry points, authentication and roles. Every method on this page answers 200 with a JSON body: a failed command reports the failure inside the body, either as the value "er" under the command name or as an error field, never with an HTTP error status.

Adapter configuration

An adapter is a JSON object in the dvb_tune list of the configuration. The API stores the object as sent; the fields below are the ones the methods on this page and the adapter start-up read, every other option is passed through to the adapter when it starts. For the full option set see the adapter configuration articles: DVB Adapters Overview, DVB-S/S2, DVB-T/T2, DVB-C.

{
    "id": "a002",
    "name": "Astra 19.2E",
    "enable": true,
    "adapter": 0,
    "device": 0,
    "type": "S2",
    "tp": "11913:H:27500",
    "lnb": "9750:10600:11700"
}

id - string. Unique adapter identifier, the id of every method below. Streams address the adapter with the input dvb://a002. The methods compare the identifier as a string, so keep it a string.
name - string, optional. Shown in the status reports; the id is used when the name is absent.
enable - boolean. true starts the adapter when it is set; a disabled adapter is stored only.
adapter - number, or the string "N.M" with the adapter and device numbers. The system adapter number: /dev/dvb/adapterN. Required unless mac is set.
device - number, optional. The frontend number within the adapter: /dev/dvb/adapterN/frontendM. 0 when absent.
mac - string, optional. Replaces adapter and device: the device is looked up by its MAC address in the list returned by List DVB devices (compared in lower case). An adapter whose MAC is not found is logged and not started.
type - string. The delivery system, case-insensitive: S, S2, T, T2, C (same as C/A and C/AC), C/B, C/C, ATSC, ISDBT. Without type the device is opened without tuning the frontend; such an adapter is not registered for Get adapter status and Monitoring.
tp - string, optional. frequency:polarization:symbolrate, expanded into the fields frequency, polarization and symbolrate at start.
lnb - string, optional. lof1:lof2:slof, expanded into lof1, lof2 and slof.
unicable - string, optional. scr:frequency, expanded into uni_scr and uni_frequency.
no_event - boolean, optional. true disables the statistics collection of the adapter, so Get adapter status reports adapter not found.
satip - string, optional. A SAT>IP server address; the adapter is received from that server. Requires adapter and type.
virtual - string, optional. satip (same as satip), ci (an external CI adapter fed by a stream: requires adapter and stream) or mpts (an adapter fed by a stream address: requires address). Virtual adapters have no frontend: their statistics carry the rate of their transport in bitrate and whether it is on air in lock, with every signal field 0 (see Adapter statistics).

A running adapter collects its frontend statistics once per second; read them with Monitoring or Get adapter status. Every start or stop of a device is pushed to the WebSocket clients as adapter_status_update; see Events.

Get adapter configuration

Request: POST /control/. Control and observer.

{
    "cmd": "get-adapter",
    "id": "a002"
}

id - string, required. Adapter identifier.

Response:

{
    "get-adapter": "ok",
    "adapter": { "id": "a002", "name": "Astra 19.2E", "enable": true, "adapter": 0, "type": "S2" }
}

adapter - the stored adapter configuration object.

Unknown identifier:

{ "get-adapter": "er", "error": "adapter not found" }

Get adapter info

Request: GET /api/adapter-info or GET /api/adapter-info/{id}. Control only; an observer receives 404.

Without an identifier the reply lists every adapter:

{
    "instance": "server-1",
    "adapters": [
        { "id": "a002", "name": "Astra 19.2E", "enable": true, "adapter": 0, "type": "S2" }
    ]
}

instance - the host name of the machine, or the instance_name setting when it is defined.
adapters - array of the stored adapter configuration objects, [] when there are none.

With an identifier the reply is the stored adapter configuration object itself:

{ "id": "a002", "name": "Astra 19.2E", "enable": true, "adapter": 0, "type": "S2" }

Unknown identifier:

{ "error": "adapter not found" }

Create or update adapter

Request: POST /control/. Control only.

{
    "cmd": "set-adapter",
    "id": "a002",
    "adapter": {
        "id": "a002",
        "name": "Astra 19.2E",
        "enable": true,
        "adapter": 0,
        "type": "S2",
        "tp": "11913:H:27500",
        "lnb": "9750:10600:11700"
    }
}

id - string, optional. Identifier of the adapter to replace. When a stored adapter has this identifier it is stopped and removed from the list before the new object is inserted; when none has it, the new object is added. Without id the object is always added, even when a stored adapter carries the same adapter.id.
adapter - object, required. The adapter configuration; its own id field is the identifier the adapter is stored under. The handler does not check that adapter.id equals id: a different adapter.id renames the adapter (see below). A request without the adapter field is a Lua error in the handler and aborts the process.
gid - number, optional. Identifier generator counter of the interface: when present it is stored as gid in the configuration and echoed in the notification, so that every interface client continues the same sequence.
scan - array, optional. Stream configuration objects to add: each one is appended to the make_stream list, started unless its enable is false (a start failure, such as a missing name or empty input, is written to the log) and pushed to the WebSocket clients as {"scope": "set-stream", "stream": { ... }}. The interface sends here the channels selected after a DVB scan. The objects are stored as sent, without the table version fields that set-stream maintains.

Response:

{ "set-adapter": "ok" }

The reply is "ok" in every case, including an unknown id.

Side effects, in this order:

With id, the input list of every stream is read as address strings; a stream whose input holds an object instead of a string (see Streams API) makes the handler fail on parse_url and the process aborts, whatever the adapter. Every stream whose input list contains dvb://{id} is handled: a running one is stopped; when adapter.id differs from id the input is rewritten to dvb://{adapter.id}. The rewrite matches dvb://{id} as a Lua pattern, so an identifier with a pattern character such as - or % is not rewritten: the stream keeps the old address and is still pushed as updated. Use identifiers made of letters and digits.
With id, the running adapter with that identifier is closed, its statistics slot is freed and {"scope": "adapter_status_update", "adapter": N, "device": M, "busy": false} is pushed.
With id, the stored object with that identifier is removed from dvb_tune and {"scope": "set-adapter", "adapter": {"id": "a002", "remove": true, "up": true}} is pushed; nothing is pushed when no stored adapter had the identifier.
The new object is appended to the end of the dvb_tune list, so a replaced adapter changes its position. WebSocket clients receive {"scope": "set-adapter", "gid": 466561, "adapter": { ... }} with the object as sent; gid is absent when the configuration holds none.
With enable set to true the adapter is started and {"scope": "adapter_status_update", "adapter": N, "device": M, "busy": true} is pushed. An adapter is not started while the instance works as the fallback of a reachable master.
The stopped streams are started again from their stored configuration when they are enabled. A stream whose input was rewritten is pushed as {"scope": "set-stream", "stream": { ... }} with the updated object; a stream that kept its input is restarted silently.
The scan streams are added and started.
The configuration is saved.

Delete adapter

Request: POST /control/. Control only.

{
    "cmd": "set-adapter",
    "id": "a002",
    "adapter": {
        "remove": true
    }
}

id - string, required. Identifier of the adapter to delete.
adapter.remove - boolean, true. Other fields of adapter are ignored.

Response:

{ "set-adapter": "ok" }

Every stream with a dvb://a002 input is stopped, removed from the make_stream list and pushed as {"scope": "set-stream", "stream": {"id": "a001", "remove": true}}. The running adapter is closed (adapter_status_update with busy: false), the object is removed from the dvb_tune list, {"scope": "set-adapter", "adapter": {"id": "a002", "remove": true, "up": false}} is pushed and the configuration is saved. An unknown id changes nothing and is still answered "ok".

Toggle adapter

Turn an adapter on or off. Request: POST /control/. Control only.

{
    "cmd": "toggle-adapter",
    "id": "a002"
}

id - string, required. Adapter identifier.

Response:

{ "toggle-adapter": "ok" }

Unknown identifier:

{ "toggle-adapter": "er", "error": "adapter not found" }

Side effects: enable is inverted in the stored object (a missing enable becomes true). An adapter that was enabled is closed, its statistics slot is freed and adapter_status_update with busy: false is pushed; an adapter that is now enabled is started and adapter_status_update with busy: true is pushed. WebSocket clients receive {"scope": "set-adapter", "adapter": { ... }} with the updated object, without gid. The configuration is saved. Streams with an input on the adapter are not restarted.

Restart adapter

Request: POST /control/. Control only.

{
    "cmd": "restart-adapter",
    "id": "a002"
}

id - string, required. Adapter identifier.

Response:

{ "restart-stream": "ok" }

The reply key is restart-stream, not restart-adapter. Failure:

{ "restart-stream": "er", "error": "adapter not found" }

The failure reply is sent for an unknown identifier, for a disabled adapter, and while the instance works as the fallback of a reachable master. The restart reads the input list of every stream as address strings, with the same abort on an object item as set-adapter.

Every enabled stream with a dvb://a002 input is stopped, the running adapter is closed (statistics slot freed, adapter_status_update with busy: false), started again from its stored configuration (adapter_status_update with busy: true) and the streams are started again. The configuration is not changed and no set-adapter notification is sent.

Check adapter

Request: POST /control/. Control and observer.

{
    "cmd": "check-adapter",
    "id": "a002"
}

id - string, required. Adapter identifier.

Response:

{
    "check-adapter": "ok",
    "adapter": { "id": "a002", "name": "Astra 19.2E", "enable": true, "adapter": 0, "type": "S2" }
}

adapter - the stored adapter configuration object. The reply carries no runtime status; use Get adapter status or Monitoring for that.

Unknown identifier:

{ "check-adapter": "er", "error": "adapter not found" }

Get adapter status

Signal statistics of a running adapter from the monitoring module. Request: POST /control/ or GET /api/adapter-status/{id} with an optional query ?t={time}. Control only on both entry points; an observer receives 404.

{
    "cmd": "adapter-status",
    "id": "a002",
    "t": 1
}

id - string, required. Adapter identifier: the id field of the body, or the second path segment on the path entry point. The adapter must be running and have a type or a virtual field.
t - number, optional. The t field of the body, or the query parameter on the path entry point. 1 (default) returns the statistics of the last completed monitoring interval, 0 the latest one-second sample. Any other number is answered with the not implemented error; a decimal numeric string is read as its number, any other value counts as 1.

Both entry points answer with the same bodies.

The monitoring interval is the tsdb_interval setting, 60 seconds when not defined.

Response:

{
    "instance": "server-1",
    "name": "Astra 19.2E",
    "timestamp": 1758240000,
    "lock": true,
    "signal": 78,
    "signal_db": -4520,
    "snr": 62,
    "snr_db": 1380,
    "ber": 0,
    "unc": 0,
    "bitrate": 41000
}

instance - the instance_name setting; absent when the setting is not defined.
name - the adapter name, or its id when the name is not set.
timestamp - Unix time. For t=1 the end of the reported interval, 0 before the first interval has completed; for t=0 the time of the latest sample, 0 before the first sample.
lock - true if the frontend reported lock in the last sample of the span.
signal - signal level as reported by the driver: percent with the DVB API v5 status, raw driver units with the dvbapi3 option. Average over the interval for t=1, the latest sample for t=0.
signal_db - signal level in dB multiplied by 100, the last sample of the span. 0 with the dvbapi3 option.
snr - signal to noise ratio in the same units as signal, averaged for t=1.
snr_db - signal to noise ratio in dB multiplied by 100, the last sample of the span. 0 with the dvbapi3 option.
ber - bit errors as reported by the driver, summed over the interval for t=1.
unc - uncorrected blocks as reported by the driver, summed over the interval for t=1.
bitrate - Kbit/s received from the device, averaged over the interval for t=1, the latest second for t=0.

A SAT>IP or virtual adapter has no frontend: lock is its on-air state, bitrate the rate of its transport, and the signal fields are 0.

Error replies, all with status 200:

{"adapter-status": "er", "error": "adapter id not defined"} - no id string in the body, or no identifier in the path; an identifier that does not URI-decode counts as none.
{"adapter-status": "er", "id": "a002", "error": "adapter not found"} - no running adapter with a monitoring slot under this identifier: an unknown or empty identifier, a disabled adapter, an adapter with neither type nor virtual, or an adapter with no_event set.
{"adapter-status": "er", "error": "not implemented"} - t is a number other than 0 and 1.

List DVB devices

The DVB devices found under /dev/dvb on the host. Request: POST /control/. Control only.

{
    "cmd": "dvbls",
    "reset": true
}

reset - optional. Any value except false and null probes the devices again. Without it the last list is returned: Astra probes the devices in the background when it starts.

Response: a JSON array, one entry per frontend, sorted by adapter and device. Get status reports the same list as dvb_list.

[
    {
        "adapter": 0,
        "device": 0,
        "busy": true,
        "type": "S",
        "frontend": "Montage DS3103/TS2022",
        "mac": "00:17:42:00:00:00"
    },
    {
        "adapter": 1,
        "device": 0,
        "error": "failed to open [Permission denied]"
    }
]

adapter - number, the system adapter number (/dev/dvb/adapterN).
device - number, the frontend number (/dev/dvb/adapterN/frontendM).
busy - boolean, true while an adapter configuration of this instance uses the frontend, or when it was open for writing as the list was built. Absent when the frontend could not be opened at all.
type - string, the frontend class: S, C, T or ATSC. Absent when error is present.
frontend - string, the frontend name reported by the driver. Absent when error is present.
mac - string, the MAC address of the adapter when the driver exposes one; absent otherwise. Usable as the mac field of the adapter configuration.
error - string, present instead of type and frontend when the probe failed: failed to open [<reason>], failed to get frontend type or unknown frontend type [N].

Without DVB devices the reply is [].