Radio Service

Overview

Radio Service allows tuning of rtl-sdr based devices to radio stations and receive respective audio stream.

Verbs

Name	Description	JSON Parameters
subscribe	subscribe to radio events	Request: {"value": "frequency"}
unsubscribe	unsubscribe to radio events	Request: {"value": "frequency"}
frequency	get/set tuned radio frequency	Request: {"value": 101100000}
band	get/set current band type (e.g. AM, FM)	Request: {"value": "FM"} Response: {"band": "FM"}
band_supported	check if a certain band is supported	Request: {"band": "FM"} Response: {"supported": 1}
frequency_range	get frequency range for band type	Request: {"band": "FM"} Response: {"min": ..., "max": ...}
frequency_step	get frequency step/spacing for band type	Request: {"band": "FM"} Response: {"step": 200000}
start	start radio playback
stop	stop radio playback
scan_start	start scanning for station	Request: {"direction": "forward" or "backward"}
scan_stop	stop scanning for station
stereo_mode	get/set stereo or mono mode	Request: {"value": "stereo" or "mono"}
rds	get current RDS data
quality	get station quality
alternative_frequency	check an alternative frequency and retune	Request: {"value": 104900000}

Events

frequency Event JSON Response

JSON response has a single field value which is the currently tuned frequency.

station_found Event JSON Response

JSON response has a single field value of the frequency of the discovered radio station.

status Event JSON Response

JSON response has a single field value with one of the values "playing" or "stopped".

rds Event JSON Response

JSON response has 13 fields:

name which is the Programme Service (PS) name;
radiotext which is the Radio Text (RT) message;
alternatives which is an array of Alternative Frequencies (AF);
minute which is the current local time minute;
hour which is the current local time hour;
day which is the current day;
month which is the current month;
year which is the current year;
pi which is the current Programme Identification (PI) code;
pty which is the current Programme Type (PTY) code;
ta which is the Traffic Announcement (TA) code;
tp which is the Traffic Programme (TP) Identification code;
ms which is the Music Speech (MS) code.

AGL Radio Tuner Binding

FM Band Plan Selection

The FM band plan may be selected by adding:

fmbandplan=X

to the [radio] section in /etc/xdg/AGL.conf, where X is one of the following strings:

US = United States / Canada JP = Japan EU = European Union ITU-1 ITU-2

Example:

[radio]
fmbandplan=JP

Implementation Specific Confguration

USB RTL-SDR adapter

The scanning sensitivity can be tweaked by adding:

scan_squelch_level=X

to the [radio] section in /etc/xdg/AGL.conf, where X is an integer. Lower values make the scanning more sensitive. Default value is 140.

Example:

[radio]
scan_squelch_level=70

M3ULCB Kingfisher Si4689

The scanning sensitivity can be tweaked by adding:

scan_valid_snr_threshold=X
scan_valid_rssi_threshold=Y

to the [radio] section in /etc/xdg/AGL.conf, where X and Y are integers between -127 and 127. The SNR value is in units of dB, and the RSSI is in units of dBuV. Lower values make the scanning more sensitive. Default values in the Si4689 are 10 and 17, respectively. You may determine the values that the Si4689 is seeing when tuning by examining the results of tuning in the systemd journal, looking for lines like:

Example:

[radio]
scan_valid_snr_threshold=7
scan_valid_rssi_threshold=10

Known Issues

M3ULCB Kingfisher

Initial setup for a new Kingfisher board requires booting an image with Kingfisher support and running the commands:

si_init
si_firmware_update

This installs the provided firmware into the flash attached to the Si4689.

Since all operations are currently done by calling a patched version of Cogent Embedded's si_ctl utility, scanning currently cannot be interrupted. Additionally, sometimes a failure in scanning seems to result in muted state that currently has not been debugged.