dev-rds.rst

  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.