RDS analysis functions
[Mixer and Controls]

Data Structures
struct	HPI_RDS_GROUP
	Raw RDS data. More...
Typedefs
typedef HPI_RDS_DATA *	HPI_RDS_HANDLE
	RDS data structure. Handle to an RDS data structure.
typedef char *	HPI_RDS_STRING
	Pointer to a string.
Enumerations
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_API	HPI_RDS_Create (enum eHPI_RDS_type eType)
	Create an HPIRDS instance.
void HPI_API	HPI_RDS_Delete (HPI_RDS_HANDLE h)
	Delete an HPIRDS instance.
void HPI_API	HPI_RDS_Clear (HPI_RDS_HANDLE h)
	Clears internal HPIRDS data structures.
enum eHPI_RDS_errors HPI_API	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_API	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_API	HPI_RDS_Get_GroupType (HPI_RDS_HANDLE h)
	Get the group type.
char HPI_API	HPI_RDS_Get_GroupVersion (HPI_RDS_HANDLE h)
	Get the group verion.
unsigned int HPI_API	HPI_RDS_Get_PS_Ready (HPI_RDS_HANDLE h)
	Get PS (program service) name ready flag.
HPI_RDS_STRING HPI_API	HPI_RDS_Get_PS (HPI_RDS_HANDLE h)
	Get PS (program service) name.
void HPI_API	HPI_RDS_Set_RT_Threshold (HPI_RDS_HANDLE h, unsigned int nCount)
	Sets the RT (Radio Test) good character threshold.
unsigned int HPI_API	HPI_RDS_Get_RT_Ready (HPI_RDS_HANDLE h)
	Get RT (Radio Text) ready flag.
HPI_RDS_STRING HPI_API	HPI_RDS_Get_RT (HPI_RDS_HANDLE h)
	Get RT (Radio Text).
unsigned short HPI_API	HPI_RDS_Get_PI (HPI_RDS_HANDLE h)
	Get PI (Program Identification).
unsigned char HPI_API	HPI_RDS_Get_PTY (HPI_RDS_HANDLE h)
	Get PTY (Program Type).
HPI_RDS_STRING HPI_API	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_API	HPI_RDS_Get_PTY_Text (HPI_RDS_HANDLE h)
	Get PTY string.
unsigned int HPI_API	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.

1. Obtain RDS data from the tuner and call HPI_RDS_AnalyzeGroup(). This processes the RDS data and fills out internal data structures.
2. Display or log RDS fields of interest by calling HPI_RDS_Get_XXXX() functions.
3. 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);       // use if(HPI_RDS_Get_PS_Ready()) first to only get the latest change.
                szRT = HPI_RDS_Get_RT(h);       // use if(HPI_RDS_Get_RT_Ready()) first to only get the latest change.
                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 blcoks 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 before processing the RDS data. 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.

The impact of RDS errors depends on the type of group in which the error occurs. An error in a group of type 0A will have no affect whatsoever. However an error in a 2A group containing 4 characters of a Radio Text array could result in 4 characters in the text showing up as spaces. ie blank text looking like " " could appear in the middle of a text string.

HPIRDS Supported fields

PS

Program service name. Sometimes called "Dynamic" Program Service. The name of the station. This is an 8 character name 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 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_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_API 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_API HPI_RDS_Delete (  HPI_RDS_HANDLE  h  )

Delete an HPIRDS instance. Parameters: h  A previously allocated HPIRDS handle.

void HPI_API 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_API 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_API 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_API 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.

char HPI_API 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_API HPI_RDS_Get_PS_Ready (  HPI_RDS_HANDLE  h  )

Get PS (program service) name ready flag. This is set to 1 when new PS string data is available. 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_API 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. Calling this function resets the PS_Ready flag. Returns: A pointer to the PS string. Parameters: h  A previously allocated HPIRDS handle.

void HPI_API 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_API HPI_RDS_Get_RT_Ready (  HPI_RDS_HANDLE  h  )

Get RT (Radio Text) ready flag. This is set to 1 when new RT string data is available. 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_API 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. Calling this function resets the RT_Ready flag. Returns: A pointer to the RT string. Parameters: h  A previously allocated HPIRDS handle.

unsigned short HPI_API 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.

unsigned char HPI_API 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_API 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 a text description of the Program Type. Parameters: eType  Data type. uPTY  PTY code.

HPI_RDS_STRING HPI_API HPI_RDS_Get_PTY_Text (  HPI_RDS_HANDLE  h  )

Get PTY string. Tranlsates the Program Type code returned by HPI_RDS_Get_PTY() into a string. Returns: Pointer to a text description of the Program Type. Parameters: h  A previously allocated HPIRDS handle.

unsigned int HPI_API 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.

---