nrsc5.h File Reference

#include <stdint.h>
#include <stdlib.h>
#include <stdio.h>
#include <time.h>

Go to the source code of this file.

Data Structures
struct	nrsc5_sig_component_t
struct	nrsc5_sig_service_t
struct	nrsc5_sis_asd_t
struct	nrsc5_sis_dsd_t
struct	nrsc5_id3_comment_t
struct	nrsc5_event_t

Macros
#define	NRSC5_SCAN_BEGIN   87.9e6
#define	NRSC5_SCAN_END   107.9e6
#define	NRSC5_SCAN_SKIP   0.2e6
#define	NRSC5_MIME_PRIMARY_IMAGE   0xBE4B7536
#define	NRSC5_MIME_STATION_LOGO   0xD9C72536
#define	NRSC5_MIME_NAVTEQ   0x2D42AC3E
#define	NRSC5_MIME_HERE_TPEG   0x82F03DFC
#define	NRSC5_MIME_HERE_IMAGE   0xB7F03DFC
#define	NRSC5_MIME_HD_TMC   0xEECB55B6
#define	NRSC5_MIME_HDC   0x4DC66C5A
#define	NRSC5_MIME_TEXT   0xBB492AAC
#define	NRSC5_MIME_JPEG   0x1E653E9C
#define	NRSC5_MIME_PNG   0x4F328CA0
#define	NRSC5_MIME_TTN_TPEG_1   0xB39EBEB2
#define	NRSC5_MIME_TTN_TPEG_2   0x4EB03469
#define	NRSC5_MIME_TTN_TPEG_3   0x52103469
#define	NRSC5_MIME_TTN_STM_TRAFFIC   0xFF8422D7
#define	NRSC5_MIME_TTN_STM_WEATHER   0xEF042E96
#define	NRSC5_MIME_UNKNOWN_00000000   0x00000000
#define	NRSC5_MIME_UNKNOWN_B81FFAA8   0xB81FFAA8
#define	NRSC5_MIME_UNKNOWN_FFFFFFFF   0xFFFFFFFF
#define	NRSC5_AUDIO_FRAME_SAMPLES   2048
#define	NRSC5_SAMPLE_RATE_CU8   1488375
#define	NRSC5_SAMPLE_RATE_CS16_FM   744187.5
#define	NRSC5_SAMPLE_RATE_CS16_AM   46511.71875
#define	NRSC5_SAMPLE_RATE_AUDIO   44100
#define	NRSC5_API

Typedefs
typedef struct nrsc5_sig_component_t	nrsc5_sig_component_t
typedef struct nrsc5_sig_service_t	nrsc5_sig_service_t
typedef struct nrsc5_sis_asd_t	nrsc5_sis_asd_t
typedef struct nrsc5_sis_dsd_t	nrsc5_sis_dsd_t
typedef struct nrsc5_id3_comment_t	nrsc5_id3_comment_t
typedef struct nrsc5_event_t	nrsc5_event_t
typedef void(*	nrsc5_callback_t) (const nrsc5_event_t *evt, void *opaque)
typedef struct nrsc5_t	nrsc5_t

Enumerations
enum	{ NRSC5_MODE_FM , NRSC5_MODE_AM }
enum	{ NRSC5_SIG_COMPONENT_AUDIO , NRSC5_SIG_COMPONENT_DATA }
enum	{ NRSC5_AAS_TYPE_STREAM = 0 , NRSC5_AAS_TYPE_PACKET = 1 , NRSC5_AAS_TYPE_LOT = 3 }
enum	{ NRSC5_SIG_SERVICE_AUDIO , NRSC5_SIG_SERVICE_DATA }
enum	{   NRSC5_EVENT_LOST_DEVICE , NRSC5_EVENT_IQ , NRSC5_EVENT_SYNC , NRSC5_EVENT_LOST_SYNC ,   NRSC5_EVENT_MER , NRSC5_EVENT_BER , NRSC5_EVENT_HDC , NRSC5_EVENT_AUDIO ,   NRSC5_EVENT_ID3 , NRSC5_EVENT_SIG , NRSC5_EVENT_LOT , NRSC5_EVENT_SIS ,   NRSC5_EVENT_STREAM , NRSC5_EVENT_PACKET , NRSC5_EVENT_AUDIO_SERVICE , NRSC5_EVENT_STATION_ID ,   NRSC5_EVENT_STATION_NAME , NRSC5_EVENT_STATION_SLOGAN , NRSC5_EVENT_STATION_MESSAGE , NRSC5_EVENT_STATION_LOCATION ,   NRSC5_EVENT_AUDIO_SERVICE_DESCRIPTOR , NRSC5_EVENT_DATA_SERVICE_DESCRIPTOR , NRSC5_EVENT_EMERGENCY_ALERT , NRSC5_EVENT_HERE_IMAGE ,   NRSC5_EVENT_LOT_HEADER , NRSC5_EVENT_LOT_FRAGMENT }
enum	{ NRSC5_ACCESS_PUBLIC , NRSC5_ACCESS_RESTRICTED }
enum	{   NRSC5_PROGRAM_TYPE_UNDEFINED = 0 , NRSC5_PROGRAM_TYPE_NEWS = 1 , NRSC5_PROGRAM_TYPE_INFORMATION = 2 , NRSC5_PROGRAM_TYPE_SPORTS = 3 ,   NRSC5_PROGRAM_TYPE_TALK = 4 , NRSC5_PROGRAM_TYPE_ROCK = 5 , NRSC5_PROGRAM_TYPE_CLASSIC_ROCK = 6 , NRSC5_PROGRAM_TYPE_ADULT_HITS = 7 ,   NRSC5_PROGRAM_TYPE_SOFT_ROCK = 8 , NRSC5_PROGRAM_TYPE_TOP_40 = 9 , NRSC5_PROGRAM_TYPE_COUNTRY = 10 , NRSC5_PROGRAM_TYPE_OLDIES = 11 ,   NRSC5_PROGRAM_TYPE_SOFT = 12 , NRSC5_PROGRAM_TYPE_NOSTALGIA = 13 , NRSC5_PROGRAM_TYPE_JAZZ = 14 , NRSC5_PROGRAM_TYPE_CLASSICAL = 15 ,   NRSC5_PROGRAM_TYPE_RHYTHM_AND_BLUES = 16 , NRSC5_PROGRAM_TYPE_SOFT_RHYTHM_AND_BLUES = 17 , NRSC5_PROGRAM_TYPE_FOREIGN_LANGUAGE = 18 , NRSC5_PROGRAM_TYPE_RELIGIOUS_MUSIC = 19 ,   NRSC5_PROGRAM_TYPE_RELIGIOUS_TALK = 20 , NRSC5_PROGRAM_TYPE_PERSONALITY = 21 , NRSC5_PROGRAM_TYPE_PUBLIC = 22 , NRSC5_PROGRAM_TYPE_COLLEGE = 23 ,   NRSC5_PROGRAM_TYPE_SPANISH_TALK = 24 , NRSC5_PROGRAM_TYPE_SPANISH_MUSIC = 25 , NRSC5_PROGRAM_TYPE_HIP_HOP = 26 , NRSC5_PROGRAM_TYPE_WEATHER = 29 ,   NRSC5_PROGRAM_TYPE_EMERGENCY_TEST = 30 , NRSC5_PROGRAM_TYPE_EMERGENCY = 31 , NRSC5_PROGRAM_TYPE_TRAFFIC = 65 , NRSC5_PROGRAM_TYPE_SPECIAL_READING_SERVICES = 76 }
enum	{ NRSC5_BLEND_DISABLE , NRSC5_BLEND_SELECT , NRSC5_BLEND_ENABLE }
enum	{ NRSC5_LOCATION_FORMAT_SAME , NRSC5_LOCATION_FORMAT_FIPS , NRSC5_LOCATION_FORMAT_ZIP }
enum	{   NRSC5_ALERT_CATEGORY_NON_SPECIFIC = 1 , NRSC5_ALERT_CATEGORY_GEOPHYSICAL = 2 , NRSC5_ALERT_CATEGORY_WEATHER = 3 , NRSC5_ALERT_CATEGORY_SAFETY = 4 ,   NRSC5_ALERT_CATEGORY_SECURITY = 5 , NRSC5_ALERT_CATEGORY_RESCUE = 6 , NRSC5_ALERT_CATEGORY_FIRE = 7 , NRSC5_ALERT_CATEGORY_HEALTH = 8 ,   NRSC5_ALERT_CATEGORY_ENVIRONMENTAL = 9 , NRSC5_ALERT_CATEGORY_TRANSPORTATION = 10 , NRSC5_ALERT_CATEGORY_UTILITIES = 11 , NRSC5_ALERT_CATEGORY_HAZMAT = 12 ,   NRSC5_ALERT_CATEGORY_TEST = 30 }
enum	{ NRSC5_HERE_IMAGE_TRAFFIC = 8 , NRSC5_HERE_IMAGE_WEATHER = 13 }
enum	{   NRSC5_SERVICE_DATA_TYPE_NON_SPECIFIC = 0 , NRSC5_SERVICE_DATA_TYPE_NEWS = 1 , NRSC5_SERVICE_DATA_TYPE_SPORTS = 3 , NRSC5_SERVICE_DATA_TYPE_WEATHER = 29 ,   NRSC5_SERVICE_DATA_TYPE_EMERGENCY = 31 , NRSC5_SERVICE_DATA_TYPE_TRAFFIC = 65 , NRSC5_SERVICE_DATA_TYPE_IMAGE_MAPS = 66 , NRSC5_SERVICE_DATA_TYPE_TEXT = 80 ,   NRSC5_SERVICE_DATA_TYPE_ADVERTISING = 256 , NRSC5_SERVICE_DATA_TYPE_FINANCIAL = 257 , NRSC5_SERVICE_DATA_TYPE_STOCK_TICKER = 258 , NRSC5_SERVICE_DATA_TYPE_NAVIGATION = 259 ,   NRSC5_SERVICE_DATA_TYPE_ELECTRONIC_PROGRAM_GUIDE = 260 , NRSC5_SERVICE_DATA_TYPE_AUDIO = 261 , NRSC5_SERVICE_DATA_TYPE_PRIVATE_DATA_NETWORK = 262 , NRSC5_SERVICE_DATA_TYPE_SERVICE_MAINTENANCE = 263 ,   NRSC5_SERVICE_DATA_TYPE_HD_RADIO_SYSTEM_SERVICES = 264 , NRSC5_SERVICE_DATA_TYPE_AUDIO_RELATED_DATA = 265 , NRSC5_SERVICE_DATA_TYPE_RESERVED_FOR_SPECIAL_TESTS = 511 }

Functions
NRSC5_API void	nrsc5_get_version (const char **version)
NRSC5_API void	nrsc5_service_data_type_name (unsigned int type, const char **name)
NRSC5_API void	nrsc5_program_type_name (unsigned int type, const char **name)
NRSC5_API void	nrsc5_alert_category_name (unsigned int category, const char **name)
NRSC5_API int	nrsc5_open (nrsc5_t **st, int device_index)
NRSC5_API int	nrsc5_open_file (nrsc5_t **st, FILE *fp)
NRSC5_API int	nrsc5_open_pipe (nrsc5_t **st)
NRSC5_API int	nrsc5_open_rtltcp (nrsc5_t **st, int socket)
NRSC5_API void	nrsc5_close (nrsc5_t *st)
NRSC5_API void	nrsc5_start (nrsc5_t *st)
NRSC5_API void	nrsc5_stop (nrsc5_t *st)
NRSC5_API int	nrsc5_set_mode (nrsc5_t *st, int mode)
NRSC5_API int	nrsc5_set_bias_tee (nrsc5_t *st, int on)
NRSC5_API int	nrsc5_set_direct_sampling (nrsc5_t *st, int on)
NRSC5_API int	nrsc5_set_freq_correction (nrsc5_t *st, int ppm_error)
NRSC5_API void	nrsc5_get_frequency (nrsc5_t *st, float *freq)
NRSC5_API int	nrsc5_set_frequency (nrsc5_t *st, float freq)
NRSC5_API void	nrsc5_get_gain (nrsc5_t *st, float *gain)
NRSC5_API int	nrsc5_set_gain (nrsc5_t *st, float gain)
NRSC5_API void	nrsc5_set_auto_gain (nrsc5_t *st, int enabled)
NRSC5_API void	nrsc5_set_callback (nrsc5_t *st, nrsc5_callback_t callback, void *opaque)
NRSC5_API int	nrsc5_pipe_samples_cu8 (nrsc5_t *st, const uint8_t *samples, unsigned int length)
NRSC5_API int	nrsc5_pipe_samples_cs16 (nrsc5_t *st, const int16_t *samples, unsigned int length)

Detailed Description

External API for the nrsc5 library.

Macro Definition Documentation

NRSC5_AUDIO_FRAME_SAMPLES

#define NRSC5_AUDIO_FRAME_SAMPLES   2048

Number of audio samples per HDC frame

NRSC5_MIME_HDC

#define NRSC5_MIME_HDC   0x4DC66C5A

MIME type for HD Codec audio

NRSC5_MIME_JPEG

#define NRSC5_MIME_JPEG   0x1E653E9C

MIME type for JPEG image

NRSC5_MIME_PNG

#define NRSC5_MIME_PNG   0x4F328CA0

MIME type for PNG image

NRSC5_MIME_PRIMARY_IMAGE

#define NRSC5_MIME_PRIMARY_IMAGE   0xBE4B7536

MIME type for album art

NRSC5_MIME_STATION_LOGO

#define NRSC5_MIME_STATION_LOGO   0xD9C72536

MIME type for station logo

NRSC5_MIME_TEXT

#define NRSC5_MIME_TEXT   0xBB492AAC

MIME type for text file

NRSC5_SAMPLE_RATE_AUDIO

#define NRSC5_SAMPLE_RATE_AUDIO   44100

Sample rate of outgoing audio

NRSC5_SAMPLE_RATE_CS16_AM

#define NRSC5_SAMPLE_RATE_CS16_AM   46511.71875

Sample rate at which nrsc5_pipe_samples_cs16() expects samples (AM only)

NRSC5_SAMPLE_RATE_CS16_FM

#define NRSC5_SAMPLE_RATE_CS16_FM   744187.5

Sample rate at which nrsc5_pipe_samples_cs16() expects samples (FM only)

NRSC5_SAMPLE_RATE_CU8

#define NRSC5_SAMPLE_RATE_CU8   1488375

Sample rate at which nrsc5_pipe_samples_cu8() expects samples (FM or AM)

Typedef Documentation

nrsc5_callback_t

typedef void(* nrsc5_callback_t) (const nrsc5_event_t *evt, void *opaque)

Prototype for a user event handling callback function. The function will be invoked with a pointer to the nrsc5_event_t and a pointer to a second contextual argument, established by nrsc5_set_callback().

nrsc5_event_t

typedef struct nrsc5_event_t nrsc5_event_t

Defines a typename for struct nrsc5_event_t

nrsc5_id3_comment_t

typedef struct nrsc5_id3_comment_t nrsc5_id3_comment_t

Defines a typename for struct nrsc5_id3_comment_t

nrsc5_sig_component_t

typedef struct nrsc5_sig_component_t nrsc5_sig_component_t

Defines a typename for struct nrsc5_sig_component_t

nrsc5_sig_service_t

typedef struct nrsc5_sig_service_t nrsc5_sig_service_t

Defines a typename for struct nrsc5_sig_service_t

nrsc5_sis_asd_t

typedef struct nrsc5_sis_asd_t nrsc5_sis_asd_t

Defines a typename for struct nrsc5_sis_asd_t

nrsc5_sis_dsd_t

typedef struct nrsc5_sis_dsd_t nrsc5_sis_dsd_t

Defines a typename for struct nrsc5_sis_dsd_t

nrsc5_t

typedef struct nrsc5_t nrsc5_t

An opaque data type used by API functions to represent session information. Applications should acquire a pointer to one via the open_ functions: nrsc5_open(), nrsc5_open_file(), nrsc5_open_pipe(), or nrsc5_open_rtltcp().

Function Documentation

nrsc5_alert_category_name()

NRSC5_API void nrsc5_alert_category_name	(	unsigned int	category,
		const char **	name
	)

Retrieves a string corresponding to an alert category.

Parameters

[in]	type	an alert category integer.
[out]	name	character pointer to a string naming the alert category

This name will be quite short, e.g. "Weather" or "Safety". If the type is not recognized, it will be the string "Unknown".

nrsc5_close()

NRSC5_API void nrsc5_close

(

nrsc5_t *

st

)

Closes an nrsc5 session.

Parameters

[in]

st

pointer to an nrsc5_t

Any worker thread is signalled to exit, files and sockets are closed, and I/O buffers are freed.

nrsc5_get_frequency()

NRSC5_API void nrsc5_get_frequency	(	nrsc5_t *	st,
		float *	freq
	)

Retrieve the frequency to which the device is currently tuned if initialized to a local dongle, otherwise the cached frequency.

Parameters

[in]	st	pointer to an nrsc5_t session object
[out]	freq	frequency in Hz

nrsc5_get_gain()

NRSC5_API void nrsc5_get_gain	(	nrsc5_t *	st,
		float *	gain
	)

Retrieve the actual receiver gain.

Parameters

[in]	st	pointer to an nrsc5_t session object
[out]	gain	in dB

nrsc5_get_version()

NRSC5_API void nrsc5_get_version

(

const char **

version

)

Retrieves the version string of the library.

Parameters

[out]

version

character pointer that will reference the version string.

nrsc5_open()

NRSC5_API int nrsc5_open	(	nrsc5_t **	st,
		int	device_index
	)

Initializes a session for a particular RTLSDR radio dongle.

Parameters

[out]	st	handle for an nrsc5_t
[in]	device_index	the RTLSDR device index

Returns

0 on success, nonzero on error

The device_index is commonly 0 on systems with a single radio dongle. This, or another open_ command should be issued before using the other API functions that need an nrsc5_t session handle. This function will allocate and initialize an opaque nsrc5_t struct and set the pointer result to it on success. It uses librtlsdr to:

• open the RTLSDR device indicated by device_index
• set the sample rate to constant SAMPLE_RATE
• set the tuner gain mode to 1 (auto)
• set offset tuning to 1

Other session options are initialized to defaults, e.g. mode to FM. It creates (but does not start) a worker thread.

nrsc5_open_file()

NRSC5_API int nrsc5_open_file	(	nrsc5_t **	st,
		FILE *	fp
	)

Initializes a session given an open FILE pointer.

Parameters

[out]	st	handle for an nrsc5_t
[in]	fp	FILE pointer handle with nrsc5 data

Returns

0 on success, nonzero on error

nrsc5_open_pipe()

NRSC5_API int nrsc5_open_pipe

(

nrsc5_t **

st

)

Initializes a session for use with a pipe.

Parameters

[out]

st

handle for an nrsc5_t

Returns

0 on success, nonzero on error

nrsc5_open_rtltcp()

NRSC5_API int nrsc5_open_rtltcp	(	nrsc5_t **	st,
		int	socket
	)

Initializes a session given a TCP socket file descriptor.

Parameters

[out]	st	handle for an nrsc5_t
[in]	socket	the TCP socket with nrsc5 data

Returns

0 on success, nonzero on error

nrsc5_pipe_samples_cs16()

NRSC5_API int nrsc5_pipe_samples_cs16	(	nrsc5_t *	st,
		const int16_t *	samples,
		unsigned int	length
	)

Push an IQ input array of 16-bit signed samples into the demodulator.

Parameters

[in]	st	pointer to an nrsc5_t session object
[in]	samples	pointer to an array 16-bit signed samples
[in]	length	the number of samples in the array

See also

NRSC5_SAMPLE_RATE_CS16_FM & NRSC5_SAMPLE_RATE_CS16_AM for required sample rate

Returns

0 on success, nonzero on error

nrsc5_pipe_samples_cu8()

NRSC5_API int nrsc5_pipe_samples_cu8	(	nrsc5_t *	st,
		const uint8_t *	samples,
		unsigned int	length
	)

Push an IQ array of 8-bit unsigned samples into the demodulator.

Parameters

[in]	st	pointer to an nrsc5_t session object
[in]	samples	pointer to an array 8-bit unsigned samples
[in]	length	the number of samples in the array

See also

NRSC5_SAMPLE_RATE_CU8 for required sample rate

Returns

0 on success, nonzero on error

nrsc5_program_type_name()

NRSC5_API void nrsc5_program_type_name	(	unsigned int	type,
		const char **	name
	)

Retrieves a string corresponding to a program type.

Parameters

[in]	type	a program data type integer.
[out]	name	character pointer to a string naming the service type

This name will be quite short, e.g. "News" or "Rock". If the type is not recognized, it will be the string "Unknown".

nrsc5_service_data_type_name()

NRSC5_API void nrsc5_service_data_type_name	(	unsigned int	type,
		const char **	name
	)

Retrieves a string corresponding to a service data type.

Parameters

[in]	type	a service data type integer.
[out]	name	character pointer to a string naming the service type

This name will be quite short, e.g. "News" or "Weather". If the type is not recognized, it will be the string "Unknown".

nrsc5_set_auto_gain()

NRSC5_API void nrsc5_set_auto_gain	(	nrsc5_t *	st,
		int	enabled
	)

Enable or disable receiver auto-gain control.

Parameters

[in]	st	pointer to an nrsc5_t session object
[in]	enabled	set to 1 to enable auto gain, 0 to disable

nrsc5_set_bias_tee()

NRSC5_API int nrsc5_set_bias_tee	(	nrsc5_t *	st,
		int	on
	)

Enable or disable the bias-T for the radio.

Parameters

[in]	st	pointer to an nrsc5_t session object
[in]	on	1 indicates enabled, and 0 indicates disabled

Returns

Return 0 on success or nonzero on error.

This works with both a local SDR and over a TCP connection. A Bias-T is often used to power a low noise amplifier by injecting DC on the antenna cable. Do not enable this unless you know you have an LNA and compatible antenna.

nrsc5_set_callback()

NRSC5_API void nrsc5_set_callback	(	nrsc5_t *	st,
		nrsc5_callback_t	callback,
		void *	opaque
	)

Establish a callback function.

Parameters

[in]	st	pointer to an nrsc5_t session object
[in]	callback	pointer to an event handling function of two arguments
[in]	opaque	pointer to the function's intended 2nd argument

nrsc5_set_direct_sampling()

NRSC5_API int nrsc5_set_direct_sampling	(	nrsc5_t *	st,
		int	on
	)

Enable or disable direct sampling.

Parameters

[in]	st	pointer to an nrsc5_t session object
[in]	on	1 indicates enabled, and 0 indicates disabled

Returns

0 on success or nonzero on error.

This works with both a local SDR and over a TCP connection.

nrsc5_set_freq_correction()

NRSC5_API int nrsc5_set_freq_correction	(	nrsc5_t *	st,
		int	ppm_error
	)

Adjust the radio frequency correction.

Parameters

[in]	st	pointer to an nrsc5_t session object
[in]	ppm_error	correction offset in parts-per-million

Returns

Return 0 on success or nonzero on error.

This works with both a local SDR and over a TCP connection.

nrsc5_set_frequency()

NRSC5_API int nrsc5_set_frequency	(	nrsc5_t *	st,
		float	freq
	)

Sets the frequency to which the receiver is tuned.

Parameters

[in]	st	pointer to an nrsc5_t session object
[out]	freq	frequency in Hz

Returns

0 on success or nonzero on error

This function may only be called when the device is stopped. Input, output are reset. Gain is reset if auto-gain is enabled. Works with both a local SDR and over a TCP connection.

nrsc5_set_gain()

NRSC5_API int nrsc5_set_gain	(	nrsc5_t *	st,
		float	gain
	)

Set the receiver gain.

Parameters

[in]	st	pointer to an nrsc5_t session object
[in]	gain	in dB

Returns

0 on success or nonzero on error

nrsc5_set_mode()

NRSC5_API int nrsc5_set_mode	(	nrsc5_t *	st,
		int	mode
	)

Set the session mode to AM or FM.

Parameters

[in]	st	pointer to an nrsc5_t session object
[in]	mode	either NRSC5_MODE_FM or NRSC5_MODE_AM

Returns

0 on success or nonzero on error.

nrsc5_start()

NRSC5_API void nrsc5_start

(

nrsc5_t *

st

)

Signals the worker to start demodulation.

Parameters

[in]

st

pointer to an nrsc5_t session object

nrsc5_stop()

NRSC5_API void nrsc5_stop

(

nrsc5_t *

st

)

Signals the worker to stop demodulation.

Parameters

[in]

st

pointer to an nrsc5_t session object

This function will block until the worker is stopped.