1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later 2 3.. _rds: 4 5************* 6RDS Interface 7************* 8 9The Radio Data System transmits supplementary information in binary 10format, for example the station name or travel information, on an 11inaudible audio subcarrier of a radio program. This interface is aimed 12at devices capable of receiving and/or transmitting RDS information. 13 14For more information see the core RDS standard :ref:`iec62106` and the 15RBDS standard :ref:`nrsc4`. 16 17.. note:: 18 19 Note that the RBDS standard as is used in the USA is almost 20 identical to the RDS standard. Any RDS decoder/encoder can also handle 21 RBDS. Only some of the fields have slightly different meanings. See the 22 RBDS standard for more information. 23 24The RBDS standard also specifies support for MMBS (Modified Mobile 25Search). This is a proprietary format which seems to be discontinued. 26The RDS interface does not support this format. Should support for MMBS 27(or the so-called 'E blocks' in general) be needed, then please contact 28the linux-media mailing list: 29`https://linuxtv.org/lists.php <https://linuxtv.org/lists.php>`__. 30 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 72.. _reading-rds-data: 73 74Reading RDS data 75================ 76 77RDS data can be read from the radio device with the 78:ref:`read() <func-read>` function. The data is packed in groups of 79three bytes. 80 81 82.. _writing-rds-data: 83 84Writing RDS data 85================ 86 87RDS data can be written to the radio device with the 88:ref:`write() <func-write>` function. The data is packed in groups of 89three bytes, as follows: 90 91 92RDS datastructures 93================== 94 95 96.. c:type:: v4l2_rds_data 97 98.. tabularcolumns:: |p{2.5cm}|p{2.5cm}|p{12.5cm}| 99 100.. flat-table:: struct v4l2_rds_data 101 :header-rows: 0 102 :stub-columns: 0 103 :widths: 1 1 5 104 105 * - __u8 106 - ``lsb`` 107 - Least Significant Byte of RDS Block 108 * - __u8 109 - ``msb`` 110 - Most Significant Byte of RDS Block 111 * - __u8 112 - ``block`` 113 - Block description 114 115 116 117.. _v4l2-rds-block: 118 119.. tabularcolumns:: |p{2.9cm}|p{14.6cm}| 120 121.. flat-table:: Block description 122 :header-rows: 0 123 :stub-columns: 0 124 :widths: 1 5 125 126 * - Bits 0-2 127 - Block (aka offset) of the received data. 128 * - Bits 3-5 129 - Deprecated. Currently identical to bits 0-2. Do not use these 130 bits. 131 * - Bit 6 132 - Corrected bit. Indicates that an error was corrected for this data 133 block. 134 * - Bit 7 135 - Error bit. Indicates that an uncorrectable error occurred during 136 reception of this block. 137 138 139 140.. _v4l2-rds-block-codes: 141 142.. tabularcolumns:: |p{6.4cm}|p{2.0cm}|p{1.2cm}|p{7.9cm}| 143 144.. flat-table:: Block defines 145 :header-rows: 0 146 :stub-columns: 0 147 :widths: 1 1 1 5 148 149 * - V4L2_RDS_BLOCK_MSK 150 - 151 - 7 152 - Mask for bits 0-2 to get the block ID. 153 * - V4L2_RDS_BLOCK_A 154 - 155 - 0 156 - Block A. 157 * - V4L2_RDS_BLOCK_B 158 - 159 - 1 160 - Block B. 161 * - V4L2_RDS_BLOCK_C 162 - 163 - 2 164 - Block C. 165 * - V4L2_RDS_BLOCK_D 166 - 167 - 3 168 - Block D. 169 * - V4L2_RDS_BLOCK_C_ALT 170 - 171 - 4 172 - Block C'. 173 * - V4L2_RDS_BLOCK_INVALID 174 - read-only 175 - 7 176 - An invalid block. 177 * - V4L2_RDS_BLOCK_CORRECTED 178 - read-only 179 - 0x40 180 - A bit error was detected but corrected. 181 * - V4L2_RDS_BLOCK_ERROR 182 - read-only 183 - 0x80 184 - An uncorrectable error occurred. 185