Data Structures
struct	HPI_RDS_GROUP
	Raw RDS data. More...
Typedefs
typedef struct HPI_RDS_DATA *	HPI_RDS_HANDLE
	RDS data structure.
typedef char *	HPI_RDS_STRING
	Pointer to a string.
Enumerations
enum	eHPI_RDS_type { HPI_RDS_DATATYPE_RDS = 0, HPI_RDS_DATATYPE_RBDS = 1 }
	Data types for PTY string translation. More...
enum	eHPI_RDS_errors { HPI_RDS_ERROR_NOERROR = 0, HPI_RDS_ERROR_UNKNOWN_GROUP = 1, HPI_RDS_ERROR_INVALID_DATASIZE = 2, HPI_RDS_ERROR_BLOCK_DATA = 3, HPI_RDS_ERROR_HANDLE = 4 }
	Error codes returned from HPI_RDS_AnalyzeGroup(). More...
Functions
HPI_RDS_HANDLE	HPI_RDS_Create (enum eHPI_RDS_type eType)
	Create an HPIRDS instance.
void	HPI_RDS_Delete (HPI_RDS_HANDLE h)
	Delete an HPIRDS instance.
void	HPI_RDS_Clear (HPI_RDS_HANDLE h)
	Clears internal HPIRDS data structures.
enum eHPI_RDS_errors	HPI_RDS_AnalyzeGroup (HPI_RDS_HANDLE h, const char *pData, const unsigned int nDataSize)
	Analyze a block of RDS data.
enum eHPI_RDS_errors	HPI_RDS_Get_BlockErrorCounts (HPI_RDS_HANDLE h, unsigned int uBlock0, unsigned int uBlock1, unsigned int uBlock2, unsigned int uBlock3)
	Get error counts per block.
unsigned int	HPI_RDS_Get_GroupType (HPI_RDS_HANDLE h)
	Get the group type.
enum eHPI_RDS_type	HPI_RDS_Get_RdsType (HPI_RDS_HANDLE h)
	Get RDS type.
enum eHPI_RDS_type	HPI_RDS_Set_RdsType (HPI_RDS_HANDLE h, enum eHPI_RDS_type eType)
	Set RDS type.
char	HPI_RDS_Get_GroupVersion (HPI_RDS_HANDLE h)
	Get the group verion.
unsigned int	HPI_RDS_Get_PS_Ready (HPI_RDS_HANDLE h)
	Get PS (program service) name ready flag.
HPI_RDS_STRING	HPI_RDS_Get_PS (HPI_RDS_HANDLE h)
	Get PS (program service) name.
void	HPI_RDS_Set_RT_Threshold (HPI_RDS_HANDLE h, unsigned int nCount)
	Sets the RT (Radio Test) good character threshold.
unsigned int	HPI_RDS_Get_RT_Ready (HPI_RDS_HANDLE h)
	Get RT (Radio Text) ready flag.
HPI_RDS_STRING	HPI_RDS_Get_RT (HPI_RDS_HANDLE h)
	Get RT (Radio Text).
unsigned short	HPI_RDS_Get_PI (HPI_RDS_HANDLE h)
	Get PI (Program Identification).
uint8_t	HPI_RDS_Get_PTY (HPI_RDS_HANDLE h)
	Get PTY (Program Type).
HPI_RDS_STRING	HPI_RDS_Get_PTY_Translate (enum eHPI_RDS_type eType, unsigned int uPTY)
	Get PTY (Program Type) text given PTY number and data type.
HPI_RDS_STRING	HPI_RDS_Get_PTY_Text (HPI_RDS_HANDLE h)
	Get PTY string.
unsigned int	HPI_RDS_Get_TP (HPI_RDS_HANDLE h)
	Get TP (Traffic Program).

Detailed Description

HPIRDS Introduction

The RDS analysis functions outlined below constitute an extendable set of functions that can be used to extract RDS information from a "raw" RDS bitstream. The idea is that after creating an HPIRDS object, groups of RDS bits are sent to the HPIRDS object for decoding. The bits are decoded into the supported RDS bit fields and characters. RDS strings are built internally in the HPIRDS object and may be retrieved at any time.

The user does not have to do anything at all with the raw RDS data except to pass it from the tuner to the analyzer. New RDS data is output at a rate of one data block every 87 ms. The AudioScience ASI8920 has on-board buffering that can hold up to 2 seconds of RDS data per tuner.

The recommended practice is for an application to poll each tuner every second and extract and analyze all the RDS data in the data buffer.

The following steps should be performed to analyze RDS data.

Startup

Create an RDS analyzer using HPI_RDS_Create(). One analyzer should be created per stream of RDS data to analyze. This implies that HPI_RDS_Create() would be called on a per tuner basis.

Below is a code snippet to create an HPIRDS object.

        HPI_RDS_HANDLE h;
        h=HPI_RDS_Create(HPI_RDS_DATATYPE_RBDS);

Running

The following code sequence should be performed every second.

Obtain RDS data from the tuner and call HPI_RDS_AnalyzeGroup(). This processes the RDS data and fills out internal data structures.
Display or log RDS fields of interest by calling HPI_RDS_Get_XXXX() functions.
Repeat 1 until a call to HPI_Tuner_GetRDS() returns HPI_ERROR_BUFFER_EMPTY. If HPI_Tuner_GetRDS() succeeds it will return 0.

The following code shows how to call the analyze function and then shows how to query various RDS fields.

        enum eHPI_RDS_errors eRDSerror;
        int nGroupType;
        char cGroupVersion;
        char *szPS;
        char *szRT;
        char *szPTY;
        unsigned short nPI,nPTY;
        char rds[12];
        HW16 wHE=0;

        while(1)        // run the following loop until all data has been read
        {
                // Use HPI Tuner call to fill in rds structure with valid bits from the tuner.
                wHE = HPI_Tuner_GetRDS(hSubSys, hTunerControl, rds);
                if(wHE)
                        break;  // break out of the loop if there is no data available

                // Call analyze function to analyze the RDS bits.
                eRDSerror = HPI_RDS_AnalyzeGroup(h, rds, sizeof(rds));
                if(eRDSerror!=HPI_RDS_ERROR_NOERROR)
                        printf("HPIRDS error #%d\n",(int)eRDSerror);

                // Retrieve current RDS settings.
                nGroupType = HPI_RDS_Get_GroupType(h);
                cGroupVersion = HPI_RDS_Get_GroupVersion(h);
                szPS = HPI_RDS_Get_PS(h);       // call HPI_RDS_Get_PS_Ready() to check if a new or updated PS text is 'ready'.
                szRT = HPI_RDS_Get_RT(h);       // call HPI_RDS_Get_RT_Ready() to check if a new or updated radio text is 'ready'.
                nPI = HPI_RDS_Get_PI(h);
                nPTY = HPI_RDS_Get_PTY(h);
                szPTY = HPI_RDS_Get_PTY_Text(h);
        }

Shutdown

Destroy the RDS object by calling HPI_RDS_Delete().

HPIRDS Error handling

Occasionally there may be errors in received RDS blocks. The error counts for each of the 4 16-bit RDS blocks is appended to the end of the RDS data that is returned from a call to HPI_Tuner_GetRDS(). The HPI_RDS_AnalyzeGroup() function checks the error counts of each block before processing RDS data from that block. Error counts less than 6 indicate that there were correctable bit errors in the data. An error count of 6+ indicates there are non correctable errors and in that case a call to HPI_RDS_AnalyzeGroup() will return HPI_RDS_ERROR_BLOCK_DATA. Even if HPI_RDS_AnalyzeGroup() returns HPI_RDS_ERROR_BLOCK_DATA blocks with correctable errors have been processed the internal state of the decoder updated accordingly.

The impact of RDS errors depends on the type of group in which the error occurs. Sometimes blocks with correctable errors result in temporary incorrect text or RDS metadata. When this occurs, the next RDS data group of the same type carrying correct information will rectify the output of the decoder.

HPIRDS Supported fields

PS

Program service name. Sometimes called "Dynamic" Program Service. The name of the station. This is an 8 character name (plus 1 character for the zero terminator) returned by a call to HPI_RDS_Get_PS().

RT

Radio text, which typically shows the name of the song. This is a 64 character string (plus 1 character for the zero terminator) returned by a call to HPI_RDS_Get_RT().

HPIRDS Supported groups

This section lists the group numbers and types currently supported by this code. As different group types become a requirement, they can be added to the code in hpirds.c. The list below is obviously a subset of the total of 16 groups that could potentially be supported. Whenever an attempt is made to analyze an unsupported group, the error HPI_RDS_ERROR_UNKNOWN_GROUP will be returned.

Note that we have concatinated the number (0-15) and the type (A or B) together in the list below.

Group	Description
0A	Basic tuning and switching information
0B	Basic tuning and switching information
2A	Radio text

Typedef Documentation

typedef struct HPI_RDS_DATA* HPI_RDS_HANDLE

RDS data structure.

Handle to an RDS data structure.

typedef char* HPI_RDS_STRING

Pointer to a string.

Enumeration Type Documentation

enum eHPI_RDS_type

Data types for PTY string translation.

Enumerator:

HPI_RDS_DATATYPE_RDS	RDS bitstream.
HPI_RDS_DATATYPE_RBDS	RBDS bitstream.

enum eHPI_RDS_errors

Error codes returned from HPI_RDS_AnalyzeGroup().

Enumerator:

HPI_RDS_ERROR_NOERROR	No error.
HPI_RDS_ERROR_UNKNOWN_GROUP	Unknown group. The RDS data belonged to a group that the RDS analyzer does not currently know how to analyze. To fix this error, code for handling additional groups should be added to hpirds.c. This error does not imply that RDS is not working properly. It just means that the station transmitted an RDS group of a type that the HPI_RDS_AnanlyzeGroup() function does not know how to handle.
HPI_RDS_ERROR_INVALID_DATASIZE	Invalid datasize.
HPI_RDS_ERROR_BLOCK_DATA	Unrecoverable data error in one of the data blocks.
HPI_RDS_ERROR_HANDLE	Bad object handle.

Function Documentation

HPI_RDS_HANDLE HPI_RDS_Create ( enum eHPI_RDS_type eType )

Create an HPIRDS instance.

One of these should be created per tuner in the system.

Returns:: Returns an allocated HPIRDS handle.

Parameters:

eType The type of bitstream thsi module will handle.

void HPI_RDS_Delete ( HPI_RDS_HANDLE h )

Delete an HPIRDS instance.

Parameters:

h	A previously allocated HPIRDS handle.

void HPI_RDS_Clear ( HPI_RDS_HANDLE h )

Clears internal HPIRDS data structures.

Applications should call this after changing the tuner frequency.

Parameters:

h	A previously allocated HPIRDS handle.

enum eHPI_RDS_errors HPI_RDS_AnalyzeGroup	(	HPI_RDS_HANDLE	h,
		const char *	pData,
		const unsigned int	nDataSize
	)

Analyze a block of RDS data.

This function should be called with a group of RDS data. Here a group refers to an array of 4 16-bit unsigned shorts that contain a complete Group of RDS bits. This function analyzes the passed in data and fills in various internal fields that can then be extracted with calls to HPI_RDS_Get_xxxx() functions.

Parameters:

h A previously allocated HPIRDS handle.

pData

Pointer to raw RDS data. This data structure is used to pass data into the RDS analysis routines. The terms "group" and "block", used below, are as defined in the EDS speficiation. It makes the following assumptions.

Data in the pData array is error free.
The data is organized as a single group, containing 4 blocks, each of 16 bits, making a total of 8 bytes.

nDataSize The size of the bitstream data array. For RDS and RDBS this should be 8 bytes.

Returns:: Returns an error code. See eHPI_RDS_errors.

enum eHPI_RDS_errors HPI_RDS_Get_BlockErrorCounts	(	HPI_RDS_HANDLE	h,
		unsigned int *	uBlock0,
		unsigned int *	uBlock1,
		unsigned int *	uBlock2,
		unsigned int *	uBlock3
	)

Get error counts per block.

This function should be called if HPI_RDS_AnalyzeGroup() returns HPI_RDS_ERROR_BLOCK_DATA and the client wants to konw exactly which of the 4 RDS blocks contained un-correctable errors. It can also be called anytime after a call HPI_RDS_AnalyzeGroup() to monitor error counts.

Returns:: Returns an error code.

Parameters:

h	A previously allocated HPIRDS handle.
uBlock0	Error count for Block0. 0xff indicates uncorrectable errors.
uBlock1	Error count for Block1. 0xff indicates uncorrectable errors.
uBlock2	Error count for Block2. 0xff indicates uncorrectable errors.
uBlock3	Error count for Block3. 0xff indicates uncorrectable errors.

unsigned int HPI_RDS_Get_GroupType ( HPI_RDS_HANDLE h )

Get the group type.

The group type is a number between 0 and 15 and indicates the type of information that the last group processed contains.

Returns:: The returns group type.

Parameters:

h	A previously allocated HPIRDS handle.

enum eHPI_RDS_type HPI_RDS_Get_RdsType ( HPI_RDS_HANDLE h )

Get RDS type.

Returns:: Returns the type of bitstream this module handles.

Parameters:

h	A previously allocated HPIRDS handle.

enum eHPI_RDS_type HPI_RDS_Set_RdsType	(	HPI_RDS_HANDLE	h,
		enum eHPI_RDS_type	eType
	)

Set RDS type.

Returns:: Returns the previous value of bitstream type.

Parameters:

h	A previously allocated HPIRDS handle.
eType	The type of bitstream this module will handle.

char HPI_RDS_Get_GroupVersion ( HPI_RDS_HANDLE h )

Get the group verion.

Returns:: The returns group version returned is either 'A' or 'B'.

Parameters:

h	A previously allocated HPIRDS handle.

unsigned int HPI_RDS_Get_PS_Ready ( HPI_RDS_HANDLE h )

Get PS (program service) name ready flag.

This is set to 1 when a new complete PS string data is available or has been updated. Reading the PS string using HPI_RDS_Get_PS() resets this flag.

Returns:: A boolean value. 1 indicates new PS data is available, 0 indicates no new PS data.

Parameters:

h	A previously allocated HPIRDS handle.

HPI_RDS_STRING HPI_RDS_Get_PS ( HPI_RDS_HANDLE h )

Get PS (program service) name.

This is the name of the station and can be up to 8 characters long (plus 1 character for the zero terminator). Calling this function resets the PS_Ready flag.

Returns:: A pointer to the zero-terminated read-only PS string.

Parameters:

h	A previously allocated HPIRDS handle.

void HPI_RDS_Set_RT_Threshold	(	HPI_RDS_HANDLE	h,
		unsigned int	nCount
	)

Sets the RT (Radio Test) good character threshold.

Sometimes "bad" characters can end up in the RT string buffer. This variable defines how many times each each character in the buffer should be received before the RT buffer is considered good. An independant count is maintained for each character in the buffer. The count reset to one each time a change in character is detected.

Parameters:

h	A previously allocated HPIRDS handle.
nCount	Number of times each character must be received in an RT message before the message is considered "good". By defaul this number is set to 1.

unsigned int HPI_RDS_Get_RT_Ready ( HPI_RDS_HANDLE h )

Get RT (Radio Text) ready flag.

This is set to 1 when a new complete RT string data is available or has been updated. Reading the RT string using HPI_RDS_Get_RT() resets this flag.

Returns:: A boolean value. 1 indicates new RT data is available, 0 indicates no new RT data.

Parameters:

h	A previously allocated HPIRDS handle.

HPI_RDS_STRING HPI_RDS_Get_RT ( HPI_RDS_HANDLE h )

Get RT (Radio Text).

This is typically the title of the playing song and can be up to 64 characters long (plus 1 character for the zero terminator). Calling this function resets the RT_Ready flag.

Returns:: A pointer to the zero-terminated read-only RT string.

Parameters:

h	A previously allocated HPIRDS handle.

unsigned short HPI_RDS_Get_PI ( HPI_RDS_HANDLE h )

Get PI (Program Identification).

PI is a two byte number which identifies the country, coverage area and service. It is not normally intended for display. A change in PI code causes the initialisation of all RDS data as it indicates that the radio has been retuned. This application also facilitates the display of the current PI code.

Returns:: A pointer to the RT string.

Parameters:

h	A previously allocated HPIRDS handle.

uint8_t HPI_RDS_Get_PTY ( HPI_RDS_HANDLE h )

Get PTY (Program Type).

PTY is a 5-bit number which indicates the current program type. Examples include "no programme type", "Current affairs" and "Pop music". See below table.

PTY code	RDS Program type (EU)	RBDS Program type (USA)
0	No program type or undefined	No program type or undefined
1	News	News
2	Current affairs	Information
3	Information	Sports
4	Sport	Talk
5	Education	Rock
6	Drama	Classic Rock
7	Culture	Adult Hits
8	Science	Soft Rock
9	Varied	Top 40
10	Pop Music	Country
11	Rock Music	Oldies
12	M.O.R. Music	Soft
13	Light classical	Nostalgia
14	Serious classical	Jazz
15	Other Music	Classical
16	Weather	Rhythm and Blues
17	Finance	Soft Rhythm and Blues
18	Childrens programmes	Language
19	Social Affairs	Religious Music
20	Religion	Religious Talk
21	Phone In	Personality
22	Travel	Public
23	Leisure	College
24	Jazz Music	Unassigned
25	Country Music	Unassigned
26	National Music	Unassigned
27	Oldies Music	Unassigned
28	Folk Music	Unassigned
29	Documentary	Weather
30	Alarm Test	Emergency Test
31	Alarm	Emergency

Returns:: A pointer to the PTY string.

Parameters:

h	A previously allocated HPIRDS handle.

HPI_RDS_STRING HPI_RDS_Get_PTY_Translate	(	enum eHPI_RDS_type	eType,
		unsigned int	uPTY
	)

Get PTY (Program Type) text given PTY number and data type.

Returns:: Pointer to the zero-terminated read-only Program Type string.

Parameters:

eType	Data type.
uPTY	PTY code.

Referenced by HPI_PAD_GetProgramTypeString().

HPI_RDS_STRING HPI_RDS_Get_PTY_Text ( HPI_RDS_HANDLE h )

Get PTY string.

Translates the Program Type code returned by HPI_RDS_Get_PTY() into a string.

Returns:: Pointer to the zero-terminated read-only Program Type string.

Parameters:

h	A previously allocated HPIRDS handle.

unsigned int HPI_RDS_Get_TP ( HPI_RDS_HANDLE h )

Get TP (Traffic Program).

The traffic program code indicates that the station will broadcast traffic announcements from time to time.

Returns:: Either 1 or 0.

Parameters:

h	A previously allocated HPIRDS handle.

RDS analysis functions

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

HPIRDS Introduction

Startup

Running

Shutdown

HPIRDS Error handling

HPIRDS Supported fields

PS

RT

HPIRDS Supported groups

Typedef Documentation

Enumeration Type Documentation

Function Documentation