1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later 2.. c:namespace:: V4L 3 4.. _rds: 5 6************* 7RDS Interface 8************* 9 10The Radio Data System transmits supplementary information in binary 11format, for example the station name or travel information, on an 12inaudible audio subcarrier of a radio program. This interface is aimed 13at devices capable of receiving and/or transmitting RDS information. 14 15For more information see the core RDS standard :ref:`iec62106` and the 16RBDS standard :ref:`nrsc4`. 17 18.. note:: 19 20 Note that the RBDS standard as is used in the USA is almost 21 identical to the RDS standard. Any RDS decoder/encoder can also handle 22 RBDS. Only some of the fields have slightly different meanings. See the 23 RBDS standard for more information. 24 25The RBDS standard also specifies support for MMBS (Modified Mobile 26Search). This is a proprietary format which seems to be discontinued. 27The RDS interface does not support this format. Should support for MMBS 28(or the so-called 'E blocks' in general) be needed, then please contact 29the linux-media mailing list: 30`https://linuxtv.org/lists.php <https://linuxtv.org/lists.php>`__. 31 32Querying Capabilities 33===================== 34 35Devices supporting the RDS capturing API set the 36``V4L2_CAP_RDS_CAPTURE`` flag in the ``capabilities`` field of struct 37:c:type:`v4l2_capability` returned by the 38:ref:`VIDIOC_QUERYCAP` ioctl. Any tuner that 39supports RDS will set the ``V4L2_TUNER_CAP_RDS`` flag in the 40``capability`` field of struct :c:type:`v4l2_tuner`. If the 41driver only passes RDS blocks without interpreting the data the 42``V4L2_TUNER_CAP_RDS_BLOCK_IO`` flag has to be set, see 43:ref:`Reading RDS data <reading-rds-data>`. For future use the flag 44``V4L2_TUNER_CAP_RDS_CONTROLS`` has also been defined. However, a driver 45for a radio tuner with this capability does not yet exist, so if you are 46planning to write such a driver you should discuss this on the 47linux-media mailing list: 48`https://linuxtv.org/lists.php <https://linuxtv.org/lists.php>`__. 49 50Whether an RDS signal is present can be detected by looking at the 51``rxsubchans`` field of struct :c:type:`v4l2_tuner`: the 52``V4L2_TUNER_SUB_RDS`` will be set if RDS data was detected. 53 54Devices supporting the RDS output API set the ``V4L2_CAP_RDS_OUTPUT`` 55flag in the ``capabilities`` field of struct 56:c:type:`v4l2_capability` returned by the 57:ref:`VIDIOC_QUERYCAP` ioctl. Any modulator that 58supports RDS will set the ``V4L2_TUNER_CAP_RDS`` flag in the 59``capability`` field of struct 60:c:type:`v4l2_modulator`. In order to enable the RDS 61transmission one must set the ``V4L2_TUNER_SUB_RDS`` bit in the 62``txsubchans`` field of struct 63:c:type:`v4l2_modulator`. If the driver only passes RDS 64blocks without interpreting the data the ``V4L2_TUNER_CAP_RDS_BLOCK_IO`` 65flag has to be set. If the tuner is capable of handling RDS entities 66like program identification codes and radio text, the flag 67``V4L2_TUNER_CAP_RDS_CONTROLS`` should be set, see 68:ref:`Writing RDS data <writing-rds-data>` and 69:ref:`FM Transmitter Control Reference <fm-tx-controls>`. 70 71.. _reading-rds-data: 72 73Reading RDS data 74================ 75 76RDS data can be read from the radio device with the 77:c:func:`read()` function. The data is packed in groups of 78three bytes. 79 80.. _writing-rds-data: 81 82Writing RDS data 83================ 84 85RDS data can be written to the radio device with the 86:c:func:`write()` function. The data is packed in groups of 87three bytes, as follows: 88 89RDS datastructures 90================== 91 92.. c:type:: v4l2_rds_data 93 94.. tabularcolumns:: |p{2.5cm}|p{2.5cm}|p{12.5cm}| 95 96.. flat-table:: struct v4l2_rds_data 97 :header-rows: 0 98 :stub-columns: 0 99 :widths: 1 1 5 100 101 * - __u8 102 - ``lsb`` 103 - Least Significant Byte of RDS Block 104 * - __u8 105 - ``msb`` 106 - Most Significant Byte of RDS Block 107 * - __u8 108 - ``block`` 109 - Block description 110 111 112.. _v4l2-rds-block: 113 114.. tabularcolumns:: |p{2.9cm}|p{14.6cm}| 115 116.. flat-table:: Block description 117 :header-rows: 0 118 :stub-columns: 0 119 :widths: 1 5 120 121 * - Bits 0-2 122 - Block (aka offset) of the received data. 123 * - Bits 3-5 124 - Deprecated. Currently identical to bits 0-2. Do not use these 125 bits. 126 * - Bit 6 127 - Corrected bit. Indicates that an error was corrected for this data 128 block. 129 * - Bit 7 130 - Error bit. Indicates that an uncorrectable error occurred during 131 reception of this block. 132 133 134.. _v4l2-rds-block-codes: 135 136.. tabularcolumns:: |p{6.4cm}|p{2.0cm}|p{1.2cm}|p{7.9cm}| 137 138.. flat-table:: Block defines 139 :header-rows: 0 140 :stub-columns: 0 141 :widths: 1 1 1 5 142 143 * - V4L2_RDS_BLOCK_MSK 144 - 145 - 7 146 - Mask for bits 0-2 to get the block ID. 147 * - V4L2_RDS_BLOCK_A 148 - 149 - 0 150 - Block A. 151 * - V4L2_RDS_BLOCK_B 152 - 153 - 1 154 - Block B. 155 * - V4L2_RDS_BLOCK_C 156 - 157 - 2 158 - Block C. 159 * - V4L2_RDS_BLOCK_D 160 - 161 - 3 162 - Block D. 163 * - V4L2_RDS_BLOCK_C_ALT 164 - 165 - 4 166 - Block C'. 167 * - V4L2_RDS_BLOCK_INVALID 168 - read-only 169 - 7 170 - An invalid block. 171 * - V4L2_RDS_BLOCK_CORRECTED 172 - read-only 173 - 0x40 174 - A bit error was detected but corrected. 175 * - V4L2_RDS_BLOCK_ERROR 176 - read-only 177 - 0x80 178 - An uncorrectable error occurred. 179