1059b1c5bSMauro Carvalho Chehab.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later 2407e84cdSMauro Carvalho Chehab.. c:namespace:: V4L 354f38fcaSMauro Carvalho Chehab 454f38fcaSMauro Carvalho Chehab.. _rds: 554f38fcaSMauro Carvalho Chehab 654f38fcaSMauro Carvalho Chehab************* 754f38fcaSMauro Carvalho ChehabRDS Interface 854f38fcaSMauro Carvalho Chehab************* 954f38fcaSMauro Carvalho Chehab 1054f38fcaSMauro Carvalho ChehabThe Radio Data System transmits supplementary information in binary 1154f38fcaSMauro Carvalho Chehabformat, for example the station name or travel information, on an 1254f38fcaSMauro Carvalho Chehabinaudible audio subcarrier of a radio program. This interface is aimed 1354f38fcaSMauro Carvalho Chehabat devices capable of receiving and/or transmitting RDS information. 1454f38fcaSMauro Carvalho Chehab 1554f38fcaSMauro Carvalho ChehabFor more information see the core RDS standard :ref:`iec62106` and the 1654f38fcaSMauro Carvalho ChehabRBDS standard :ref:`nrsc4`. 1754f38fcaSMauro Carvalho Chehab 1854f38fcaSMauro Carvalho Chehab.. note:: 1954f38fcaSMauro Carvalho Chehab 2054f38fcaSMauro Carvalho Chehab Note that the RBDS standard as is used in the USA is almost 2154f38fcaSMauro Carvalho Chehab identical to the RDS standard. Any RDS decoder/encoder can also handle 2254f38fcaSMauro Carvalho Chehab RBDS. Only some of the fields have slightly different meanings. See the 2354f38fcaSMauro Carvalho Chehab RBDS standard for more information. 2454f38fcaSMauro Carvalho Chehab 2554f38fcaSMauro Carvalho ChehabThe RBDS standard also specifies support for MMBS (Modified Mobile 2654f38fcaSMauro Carvalho ChehabSearch). This is a proprietary format which seems to be discontinued. 2754f38fcaSMauro Carvalho ChehabThe RDS interface does not support this format. Should support for MMBS 2854f38fcaSMauro Carvalho Chehab(or the so-called 'E blocks' in general) be needed, then please contact 2954f38fcaSMauro Carvalho Chehabthe linux-media mailing list: 3054f38fcaSMauro Carvalho Chehab`https://linuxtv.org/lists.php <https://linuxtv.org/lists.php>`__. 3154f38fcaSMauro Carvalho Chehab 3254f38fcaSMauro Carvalho ChehabQuerying Capabilities 3354f38fcaSMauro Carvalho Chehab===================== 3454f38fcaSMauro Carvalho Chehab 3554f38fcaSMauro Carvalho ChehabDevices supporting the RDS capturing API set the 3654f38fcaSMauro Carvalho Chehab``V4L2_CAP_RDS_CAPTURE`` flag in the ``capabilities`` field of struct 3754f38fcaSMauro Carvalho Chehab:c:type:`v4l2_capability` returned by the 3854f38fcaSMauro Carvalho Chehab:ref:`VIDIOC_QUERYCAP` ioctl. Any tuner that 3954f38fcaSMauro Carvalho Chehabsupports RDS will set the ``V4L2_TUNER_CAP_RDS`` flag in the 4054f38fcaSMauro Carvalho Chehab``capability`` field of struct :c:type:`v4l2_tuner`. If the 4154f38fcaSMauro Carvalho Chehabdriver only passes RDS blocks without interpreting the data the 4254f38fcaSMauro Carvalho Chehab``V4L2_TUNER_CAP_RDS_BLOCK_IO`` flag has to be set, see 4354f38fcaSMauro Carvalho Chehab:ref:`Reading RDS data <reading-rds-data>`. For future use the flag 4454f38fcaSMauro Carvalho Chehab``V4L2_TUNER_CAP_RDS_CONTROLS`` has also been defined. However, a driver 4554f38fcaSMauro Carvalho Chehabfor a radio tuner with this capability does not yet exist, so if you are 4654f38fcaSMauro Carvalho Chehabplanning to write such a driver you should discuss this on the 4754f38fcaSMauro Carvalho Chehablinux-media mailing list: 4854f38fcaSMauro Carvalho Chehab`https://linuxtv.org/lists.php <https://linuxtv.org/lists.php>`__. 4954f38fcaSMauro Carvalho Chehab 5054f38fcaSMauro Carvalho ChehabWhether an RDS signal is present can be detected by looking at the 5154f38fcaSMauro Carvalho Chehab``rxsubchans`` field of struct :c:type:`v4l2_tuner`: the 5254f38fcaSMauro Carvalho Chehab``V4L2_TUNER_SUB_RDS`` will be set if RDS data was detected. 5354f38fcaSMauro Carvalho Chehab 5454f38fcaSMauro Carvalho ChehabDevices supporting the RDS output API set the ``V4L2_CAP_RDS_OUTPUT`` 5554f38fcaSMauro Carvalho Chehabflag in the ``capabilities`` field of struct 5654f38fcaSMauro Carvalho Chehab:c:type:`v4l2_capability` returned by the 5754f38fcaSMauro Carvalho Chehab:ref:`VIDIOC_QUERYCAP` ioctl. Any modulator that 5854f38fcaSMauro Carvalho Chehabsupports RDS will set the ``V4L2_TUNER_CAP_RDS`` flag in the 5954f38fcaSMauro Carvalho Chehab``capability`` field of struct 6054f38fcaSMauro Carvalho Chehab:c:type:`v4l2_modulator`. In order to enable the RDS 6154f38fcaSMauro Carvalho Chehabtransmission one must set the ``V4L2_TUNER_SUB_RDS`` bit in the 6254f38fcaSMauro Carvalho Chehab``txsubchans`` field of struct 6354f38fcaSMauro Carvalho Chehab:c:type:`v4l2_modulator`. If the driver only passes RDS 6454f38fcaSMauro Carvalho Chehabblocks without interpreting the data the ``V4L2_TUNER_CAP_RDS_BLOCK_IO`` 6554f38fcaSMauro Carvalho Chehabflag has to be set. If the tuner is capable of handling RDS entities 6654f38fcaSMauro Carvalho Chehablike program identification codes and radio text, the flag 6754f38fcaSMauro Carvalho Chehab``V4L2_TUNER_CAP_RDS_CONTROLS`` should be set, see 6854f38fcaSMauro Carvalho Chehab:ref:`Writing RDS data <writing-rds-data>` and 6954f38fcaSMauro Carvalho Chehab:ref:`FM Transmitter Control Reference <fm-tx-controls>`. 7054f38fcaSMauro Carvalho Chehab 7154f38fcaSMauro Carvalho Chehab.. _reading-rds-data: 7254f38fcaSMauro Carvalho Chehab 7354f38fcaSMauro Carvalho ChehabReading RDS data 7454f38fcaSMauro Carvalho Chehab================ 7554f38fcaSMauro Carvalho Chehab 7654f38fcaSMauro Carvalho ChehabRDS data can be read from the radio device with the 77407e84cdSMauro Carvalho Chehab:c:func:`read()` function. The data is packed in groups of 7854f38fcaSMauro Carvalho Chehabthree bytes. 7954f38fcaSMauro Carvalho Chehab 8054f38fcaSMauro Carvalho Chehab.. _writing-rds-data: 8154f38fcaSMauro Carvalho Chehab 8254f38fcaSMauro Carvalho ChehabWriting RDS data 8354f38fcaSMauro Carvalho Chehab================ 8454f38fcaSMauro Carvalho Chehab 8554f38fcaSMauro Carvalho ChehabRDS data can be written to the radio device with the 86407e84cdSMauro Carvalho Chehab:c:func:`write()` function. The data is packed in groups of 8754f38fcaSMauro Carvalho Chehabthree bytes, as follows: 8854f38fcaSMauro Carvalho Chehab 8954f38fcaSMauro Carvalho ChehabRDS datastructures 9054f38fcaSMauro Carvalho Chehab================== 9154f38fcaSMauro Carvalho Chehab 9254f38fcaSMauro Carvalho Chehab.. c:type:: v4l2_rds_data 9354f38fcaSMauro Carvalho Chehab 9454f38fcaSMauro Carvalho Chehab.. flat-table:: struct v4l2_rds_data 9554f38fcaSMauro Carvalho Chehab :header-rows: 0 9654f38fcaSMauro Carvalho Chehab :stub-columns: 0 9754f38fcaSMauro Carvalho Chehab :widths: 1 1 5 9854f38fcaSMauro Carvalho Chehab 9954f38fcaSMauro Carvalho Chehab * - __u8 10054f38fcaSMauro Carvalho Chehab - ``lsb`` 10154f38fcaSMauro Carvalho Chehab - Least Significant Byte of RDS Block 10254f38fcaSMauro Carvalho Chehab * - __u8 10354f38fcaSMauro Carvalho Chehab - ``msb`` 10454f38fcaSMauro Carvalho Chehab - Most Significant Byte of RDS Block 10554f38fcaSMauro Carvalho Chehab * - __u8 10654f38fcaSMauro Carvalho Chehab - ``block`` 10754f38fcaSMauro Carvalho Chehab - Block description 10854f38fcaSMauro Carvalho Chehab 10954f38fcaSMauro Carvalho Chehab 11054f38fcaSMauro Carvalho Chehab.. _v4l2-rds-block: 11154f38fcaSMauro Carvalho Chehab 11254f38fcaSMauro Carvalho Chehab.. tabularcolumns:: |p{2.9cm}|p{14.6cm}| 11354f38fcaSMauro Carvalho Chehab 11454f38fcaSMauro Carvalho Chehab.. flat-table:: Block description 11554f38fcaSMauro Carvalho Chehab :header-rows: 0 11654f38fcaSMauro Carvalho Chehab :stub-columns: 0 11754f38fcaSMauro Carvalho Chehab :widths: 1 5 11854f38fcaSMauro Carvalho Chehab 11954f38fcaSMauro Carvalho Chehab * - Bits 0-2 12054f38fcaSMauro Carvalho Chehab - Block (aka offset) of the received data. 12154f38fcaSMauro Carvalho Chehab * - Bits 3-5 12254f38fcaSMauro Carvalho Chehab - Deprecated. Currently identical to bits 0-2. Do not use these 12354f38fcaSMauro Carvalho Chehab bits. 12454f38fcaSMauro Carvalho Chehab * - Bit 6 12554f38fcaSMauro Carvalho Chehab - Corrected bit. Indicates that an error was corrected for this data 12654f38fcaSMauro Carvalho Chehab block. 12754f38fcaSMauro Carvalho Chehab * - Bit 7 12854f38fcaSMauro Carvalho Chehab - Error bit. Indicates that an uncorrectable error occurred during 12954f38fcaSMauro Carvalho Chehab reception of this block. 13054f38fcaSMauro Carvalho Chehab 13154f38fcaSMauro Carvalho Chehab 13254f38fcaSMauro Carvalho Chehab.. _v4l2-rds-block-codes: 13354f38fcaSMauro Carvalho Chehab 134*fea13a69SMauro Carvalho Chehab.. tabularcolumns:: |p{6.4cm}|p{2.0cm}|p{1.2cm}|p{7.0cm}| 13554f38fcaSMauro Carvalho Chehab 13654f38fcaSMauro Carvalho Chehab.. flat-table:: Block defines 13754f38fcaSMauro Carvalho Chehab :header-rows: 0 13854f38fcaSMauro Carvalho Chehab :stub-columns: 0 13954f38fcaSMauro Carvalho Chehab :widths: 1 1 1 5 14054f38fcaSMauro Carvalho Chehab 14154f38fcaSMauro Carvalho Chehab * - V4L2_RDS_BLOCK_MSK 14254f38fcaSMauro Carvalho Chehab - 14354f38fcaSMauro Carvalho Chehab - 7 14454f38fcaSMauro Carvalho Chehab - Mask for bits 0-2 to get the block ID. 14554f38fcaSMauro Carvalho Chehab * - V4L2_RDS_BLOCK_A 14654f38fcaSMauro Carvalho Chehab - 14754f38fcaSMauro Carvalho Chehab - 0 14854f38fcaSMauro Carvalho Chehab - Block A. 14954f38fcaSMauro Carvalho Chehab * - V4L2_RDS_BLOCK_B 15054f38fcaSMauro Carvalho Chehab - 15154f38fcaSMauro Carvalho Chehab - 1 15254f38fcaSMauro Carvalho Chehab - Block B. 15354f38fcaSMauro Carvalho Chehab * - V4L2_RDS_BLOCK_C 15454f38fcaSMauro Carvalho Chehab - 15554f38fcaSMauro Carvalho Chehab - 2 15654f38fcaSMauro Carvalho Chehab - Block C. 15754f38fcaSMauro Carvalho Chehab * - V4L2_RDS_BLOCK_D 15854f38fcaSMauro Carvalho Chehab - 15954f38fcaSMauro Carvalho Chehab - 3 16054f38fcaSMauro Carvalho Chehab - Block D. 16154f38fcaSMauro Carvalho Chehab * - V4L2_RDS_BLOCK_C_ALT 16254f38fcaSMauro Carvalho Chehab - 16354f38fcaSMauro Carvalho Chehab - 4 16454f38fcaSMauro Carvalho Chehab - Block C'. 16554f38fcaSMauro Carvalho Chehab * - V4L2_RDS_BLOCK_INVALID 16654f38fcaSMauro Carvalho Chehab - read-only 16754f38fcaSMauro Carvalho Chehab - 7 16854f38fcaSMauro Carvalho Chehab - An invalid block. 16954f38fcaSMauro Carvalho Chehab * - V4L2_RDS_BLOCK_CORRECTED 17054f38fcaSMauro Carvalho Chehab - read-only 17154f38fcaSMauro Carvalho Chehab - 0x40 17254f38fcaSMauro Carvalho Chehab - A bit error was detected but corrected. 17354f38fcaSMauro Carvalho Chehab * - V4L2_RDS_BLOCK_ERROR 17454f38fcaSMauro Carvalho Chehab - read-only 17554f38fcaSMauro Carvalho Chehab - 0x80 17654f38fcaSMauro Carvalho Chehab - An uncorrectable error occurred. 177