0001 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
0002 .. c:namespace:: V4L
0003
0004 .. _rds:
0005
0006 *************
0007 RDS Interface
0008 *************
0009
0010 The Radio Data System transmits supplementary information in binary
0011 format, for example the station name or travel information, on an
0012 inaudible audio subcarrier of a radio program. This interface is aimed
0013 at devices capable of receiving and/or transmitting RDS information.
0014
0015 For more information see the core RDS standard :ref:`iec62106` and the
0016 RBDS standard :ref:`nrsc4`.
0017
0018 .. note::
0019
0020 Note that the RBDS standard as is used in the USA is almost
0021 identical to the RDS standard. Any RDS decoder/encoder can also handle
0022 RBDS. Only some of the fields have slightly different meanings. See the
0023 RBDS standard for more information.
0024
0025 The RBDS standard also specifies support for MMBS (Modified Mobile
0026 Search). This is a proprietary format which seems to be discontinued.
0027 The RDS interface does not support this format. Should support for MMBS
0028 (or the so-called 'E blocks' in general) be needed, then please contact
0029 the linux-media mailing list:
0030 `https://linuxtv.org/lists.php <https://linuxtv.org/lists.php>`__.
0031
0032 Querying Capabilities
0033 =====================
0034
0035 Devices supporting the RDS capturing API set the
0036 ``V4L2_CAP_RDS_CAPTURE`` flag in the ``capabilities`` field of struct
0037 :c:type:`v4l2_capability` returned by the
0038 :ref:`VIDIOC_QUERYCAP` ioctl. Any tuner that
0039 supports RDS will set the ``V4L2_TUNER_CAP_RDS`` flag in the
0040 ``capability`` field of struct :c:type:`v4l2_tuner`. If the
0041 driver only passes RDS blocks without interpreting the data the
0042 ``V4L2_TUNER_CAP_RDS_BLOCK_IO`` flag has to be set, see
0043 :ref:`Reading RDS data <reading-rds-data>`. For future use the flag
0044 ``V4L2_TUNER_CAP_RDS_CONTROLS`` has also been defined. However, a driver
0045 for a radio tuner with this capability does not yet exist, so if you are
0046 planning to write such a driver you should discuss this on the
0047 linux-media mailing list:
0048 `https://linuxtv.org/lists.php <https://linuxtv.org/lists.php>`__.
0049
0050 Whether an RDS signal is present can be detected by looking at the
0051 ``rxsubchans`` field of struct :c:type:`v4l2_tuner`: the
0052 ``V4L2_TUNER_SUB_RDS`` will be set if RDS data was detected.
0053
0054 Devices supporting the RDS output API set the ``V4L2_CAP_RDS_OUTPUT``
0055 flag in the ``capabilities`` field of struct
0056 :c:type:`v4l2_capability` returned by the
0057 :ref:`VIDIOC_QUERYCAP` ioctl. Any modulator that
0058 supports RDS will set the ``V4L2_TUNER_CAP_RDS`` flag in the
0059 ``capability`` field of struct
0060 :c:type:`v4l2_modulator`. In order to enable the RDS
0061 transmission one must set the ``V4L2_TUNER_SUB_RDS`` bit in the
0062 ``txsubchans`` field of struct
0063 :c:type:`v4l2_modulator`. If the driver only passes RDS
0064 blocks without interpreting the data the ``V4L2_TUNER_CAP_RDS_BLOCK_IO``
0065 flag has to be set. If the tuner is capable of handling RDS entities
0066 like program identification codes and radio text, the flag
0067 ``V4L2_TUNER_CAP_RDS_CONTROLS`` should be set, see
0068 :ref:`Writing RDS data <writing-rds-data>` and
0069 :ref:`FM Transmitter Control Reference <fm-tx-controls>`.
0070
0071 .. _reading-rds-data:
0072
0073 Reading RDS data
0074 ================
0075
0076 RDS data can be read from the radio device with the
0077 :c:func:`read()` function. The data is packed in groups of
0078 three bytes.
0079
0080 .. _writing-rds-data:
0081
0082 Writing RDS data
0083 ================
0084
0085 RDS data can be written to the radio device with the
0086 :c:func:`write()` function. The data is packed in groups of
0087 three bytes, as follows:
0088
0089 RDS datastructures
0090 ==================
0091
0092 .. c:type:: v4l2_rds_data
0093
0094 .. flat-table:: struct v4l2_rds_data
0095 :header-rows: 0
0096 :stub-columns: 0
0097 :widths: 1 1 5
0098
0099 * - __u8
0100 - ``lsb``
0101 - Least Significant Byte of RDS Block
0102 * - __u8
0103 - ``msb``
0104 - Most Significant Byte of RDS Block
0105 * - __u8
0106 - ``block``
0107 - Block description
0108
0109
0110 .. _v4l2-rds-block:
0111
0112 .. tabularcolumns:: |p{2.9cm}|p{14.6cm}|
0113
0114 .. flat-table:: Block description
0115 :header-rows: 0
0116 :stub-columns: 0
0117 :widths: 1 5
0118
0119 * - Bits 0-2
0120 - Block (aka offset) of the received data.
0121 * - Bits 3-5
0122 - Deprecated. Currently identical to bits 0-2. Do not use these
0123 bits.
0124 * - Bit 6
0125 - Corrected bit. Indicates that an error was corrected for this data
0126 block.
0127 * - Bit 7
0128 - Error bit. Indicates that an uncorrectable error occurred during
0129 reception of this block.
0130
0131
0132 .. _v4l2-rds-block-codes:
0133
0134 .. tabularcolumns:: |p{6.4cm}|p{2.0cm}|p{1.2cm}|p{7.0cm}|
0135
0136 .. flat-table:: Block defines
0137 :header-rows: 0
0138 :stub-columns: 0
0139 :widths: 1 1 1 5
0140
0141 * - V4L2_RDS_BLOCK_MSK
0142 -
0143 - 7
0144 - Mask for bits 0-2 to get the block ID.
0145 * - V4L2_RDS_BLOCK_A
0146 -
0147 - 0
0148 - Block A.
0149 * - V4L2_RDS_BLOCK_B
0150 -
0151 - 1
0152 - Block B.
0153 * - V4L2_RDS_BLOCK_C
0154 -
0155 - 2
0156 - Block C.
0157 * - V4L2_RDS_BLOCK_D
0158 -
0159 - 3
0160 - Block D.
0161 * - V4L2_RDS_BLOCK_C_ALT
0162 -
0163 - 4
0164 - Block C'.
0165 * - V4L2_RDS_BLOCK_INVALID
0166 - read-only
0167 - 7
0168 - An invalid block.
0169 * - V4L2_RDS_BLOCK_CORRECTED
0170 - read-only
0171 - 0x40
0172 - A bit error was detected but corrected.
0173 * - V4L2_RDS_BLOCK_ERROR
0174 - read-only
0175 - 0x80
0176 - An uncorrectable error occurred.
