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.. flat-table:: struct v4l2_rds_data 95 :header-rows: 0 96 :stub-columns: 0 97 :widths: 1 1 5 98 99 * - __u8 100 - ``lsb`` 101 - Least Significant Byte of RDS Block 102 * - __u8 103 - ``msb`` 104 - Most Significant Byte of RDS Block 105 * - __u8 106 - ``block`` 107 - Block description 108 109 110.. _v4l2-rds-block: 111 112.. tabularcolumns:: |p{2.9cm}|p{14.6cm}| 113 114.. flat-table:: Block description 115 :header-rows: 0 116 :stub-columns: 0 117 :widths: 1 5 118 119 * - Bits 0-2 120 - Block (aka offset) of the received data. 121 * - Bits 3-5 122 - Deprecated. Currently identical to bits 0-2. Do not use these 123 bits. 124 * - Bit 6 125 - Corrected bit. Indicates that an error was corrected for this data 126 block. 127 * - Bit 7 128 - Error bit. Indicates that an uncorrectable error occurred during 129 reception of this block. 130 131 132.. _v4l2-rds-block-codes: 133 134.. tabularcolumns:: |p{6.4cm}|p{2.0cm}|p{1.2cm}|p{7.0cm}| 135 136.. flat-table:: Block defines 137 :header-rows: 0 138 :stub-columns: 0 139 :widths: 1 1 1 5 140 141 * - V4L2_RDS_BLOCK_MSK 142 - 143 - 7 144 - Mask for bits 0-2 to get the block ID. 145 * - V4L2_RDS_BLOCK_A 146 - 147 - 0 148 - Block A. 149 * - V4L2_RDS_BLOCK_B 150 - 151 - 1 152 - Block B. 153 * - V4L2_RDS_BLOCK_C 154 - 155 - 2 156 - Block C. 157 * - V4L2_RDS_BLOCK_D 158 - 159 - 3 160 - Block D. 161 * - V4L2_RDS_BLOCK_C_ALT 162 - 163 - 4 164 - Block C'. 165 * - V4L2_RDS_BLOCK_INVALID 166 - read-only 167 - 7 168 - An invalid block. 169 * - V4L2_RDS_BLOCK_CORRECTED 170 - read-only 171 - 0x40 172 - A bit error was detected but corrected. 173 * - V4L2_RDS_BLOCK_ERROR 174 - read-only 175 - 0x80 176 - An uncorrectable error occurred. 177