AudioScience HPI Version_4.10.
Data Structures | Typedefs | Enumerations | Functions

RDS analysis functions

Controls

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.
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.

rds_buffers.png

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

Data types for PTY string translation.

Enumerator:
HPI_RDS_DATATYPE_RDS 

RDS bitstream.

HPI_RDS_DATATYPE_RBDS 

RBDS bitstream.

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:
eTypeThe type of bitstream thsi module will handle.
void HPI_RDS_Delete ( HPI_RDS_HANDLE  h)

Delete an HPIRDS instance.

Parameters:
hA 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:
hA 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:
hA previously allocated HPIRDS handle.
pDataPointer 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.
nDataSizeThe 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:
hA previously allocated HPIRDS handle.
uBlock0Error count for Block0. 0xff indicates uncorrectable errors.
uBlock1Error count for Block1. 0xff indicates uncorrectable errors.
uBlock2Error count for Block2. 0xff indicates uncorrectable errors.
uBlock3Error 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:
hA previously allocated HPIRDS 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:
hA 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 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:
hA 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. Calling this function resets the PS_Ready flag.

Returns:
A pointer to the PS string.
Parameters:
hA 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:
hA previously allocated HPIRDS handle.
nCountNumber 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 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:
hA 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. Calling this function resets the RT_Ready flag.

Returns:
A pointer to the RT string.
Parameters:
hA 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:
hA 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)

0No program type or undefinedNo program type or undefined
1NewsNews
2Current affairsInformation
3InformationSports
4SportTalk
5EducationRock
6DramaClassic Rock
7CultureAdult Hits
8ScienceSoft Rock
9VariedTop 40
10Pop MusicCountry
11Rock MusicOldies
12M.O.R. MusicSoft
13Light classicalNostalgia
14Serious classicalJazz
15Other MusicClassical
16WeatherRhythm and Blues
17FinanceSoft Rhythm and Blues
18Childrens programmesLanguage
19Social AffairsReligious Music
20ReligionReligious Talk
21Phone InPersonality
22TravelPublic
23LeisureCollege
24Jazz MusicUnassigned
25Country MusicUnassigned
26National MusicUnassigned
27Oldies MusicUnassigned
28Folk MusicUnassigned
29DocumentaryWeather
30Alarm TestEmergency Test
31AlarmEmergency
Returns:
A pointer to the PTY string.
Parameters:
hA 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 a text description of the Program Type.
Parameters:
eTypeData type.
uPTYPTY code.

Referenced by HPI_PAD_GetProgramTypeString().

HPI_RDS_STRING 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:
hA 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:
hA previously allocated HPIRDS handle.