Commit | Line | Data |
---|---|---|
5377d91f MH |
1 | .. -*- coding: utf-8; mode: rst -*- |
2 | ||
3 | .. _rds: | |
4 | ||
5 | ************* | |
6 | RDS Interface | |
7 | ************* | |
8 | ||
9 | The Radio Data System transmits supplementary information in binary | |
10 | format, for example the station name or travel information, on an | |
11 | inaudible audio subcarrier of a radio program. This interface is aimed | |
12 | at devices capable of receiving and/or transmitting RDS information. | |
13 | ||
14 | For more information see the core RDS standard :ref:`iec62106` and the | |
15 | RBDS standard :ref:`nrsc4`. | |
16 | ||
b6b6e678 MCC |
17 | .. note:: |
18 | ||
19 | Note that the RBDS standard as is used in the USA is almost | |
706f8a99 MCC |
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. | |
5377d91f MH |
23 | |
24 | The RBDS standard also specifies support for MMBS (Modified Mobile | |
25 | Search). This is a proprietary format which seems to be discontinued. | |
26 | The 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 | |
28 | the linux-media mailing list: | |
29 | `https://linuxtv.org/lists.php <https://linuxtv.org/lists.php>`__. | |
30 | ||
31 | ||
32 | Querying Capabilities | |
33 | ===================== | |
34 | ||
35 | Devices supporting the RDS capturing API set the | |
36 | ``V4L2_CAP_RDS_CAPTURE`` flag in the ``capabilities`` field of struct | |
e8be7e97 | 37 | :c:type:`v4l2_capability` returned by the |
7347081e | 38 | :ref:`VIDIOC_QUERYCAP` ioctl. Any tuner that |
5377d91f | 39 | supports RDS will set the ``V4L2_TUNER_CAP_RDS`` flag in the |
e8be7e97 | 40 | ``capability`` field of struct :c:type:`v4l2_tuner`. If the |
5377d91f MH |
41 | driver 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 | |
45 | for a radio tuner with this capability does not yet exist, so if you are | |
46 | planning to write such a driver you should discuss this on the | |
47 | linux-media mailing list: | |
48 | `https://linuxtv.org/lists.php <https://linuxtv.org/lists.php>`__. | |
49 | ||
50 | Whether an RDS signal is present can be detected by looking at the | |
e8be7e97 | 51 | ``rxsubchans`` field of struct :c:type:`v4l2_tuner`: the |
5377d91f MH |
52 | ``V4L2_TUNER_SUB_RDS`` will be set if RDS data was detected. |
53 | ||
54 | Devices supporting the RDS output API set the ``V4L2_CAP_RDS_OUTPUT`` | |
55 | flag in the ``capabilities`` field of struct | |
e8be7e97 | 56 | :c:type:`v4l2_capability` returned by the |
7347081e | 57 | :ref:`VIDIOC_QUERYCAP` ioctl. Any modulator that |
5377d91f MH |
58 | supports RDS will set the ``V4L2_TUNER_CAP_RDS`` flag in the |
59 | ``capability`` field of struct | |
e8be7e97 | 60 | :c:type:`v4l2_modulator`. In order to enable the RDS |
5377d91f MH |
61 | transmission one must set the ``V4L2_TUNER_SUB_RDS`` bit in the |
62 | ``txsubchans`` field of struct | |
e8be7e97 | 63 | :c:type:`v4l2_modulator`. If the driver only passes RDS |
5377d91f MH |
64 | blocks without interpreting the data the ``V4L2_TUNER_CAP_RDS_BLOCK_IO`` |
65 | flag has to be set. If the tuner is capable of handling RDS entities | |
66 | like 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 | ||
74 | Reading RDS data | |
75 | ================ | |
76 | ||
77 | RDS data can be read from the radio device with the | |
78 | :ref:`read() <func-read>` function. The data is packed in groups of | |
79 | three bytes. | |
80 | ||
81 | ||
82 | .. _writing-rds-data: | |
83 | ||
84 | Writing RDS data | |
85 | ================ | |
86 | ||
87 | RDS data can be written to the radio device with the | |
88 | :ref:`write() <func-write>` function. The data is packed in groups of | |
89 | three bytes, as follows: | |
90 | ||
91 | ||
92 | RDS datastructures | |
93 | ================== | |
94 | ||
95 | ||
e8be7e97 | 96 | .. c:type:: v4l2_rds_data |
5377d91f | 97 | |
5bd4bb78 MCC |
98 | .. tabularcolumns:: |p{2.5cm}|p{2.5cm}|p{12.5cm}| |
99 | ||
5377d91f MH |
100 | .. flat-table:: struct v4l2_rds_data |
101 | :header-rows: 0 | |
102 | :stub-columns: 0 | |
103 | :widths: 1 1 5 | |
104 | ||
105 | ||
106 | - .. row 1 | |
107 | ||
108 | - __u8 | |
109 | ||
110 | - ``lsb`` | |
111 | ||
112 | - Least Significant Byte of RDS Block | |
113 | ||
114 | - .. row 2 | |
115 | ||
116 | - __u8 | |
117 | ||
118 | - ``msb`` | |
119 | ||
120 | - Most Significant Byte of RDS Block | |
121 | ||
122 | - .. row 3 | |
123 | ||
124 | - __u8 | |
125 | ||
126 | - ``block`` | |
127 | ||
128 | - Block description | |
129 | ||
130 | ||
131 | ||
132 | .. _v4l2-rds-block: | |
133 | ||
5bd4bb78 MCC |
134 | .. tabularcolumns:: |p{2.9cm}|p{14.6cm}| |
135 | ||
5377d91f MH |
136 | .. flat-table:: Block description |
137 | :header-rows: 0 | |
138 | :stub-columns: 0 | |
139 | :widths: 1 5 | |
140 | ||
141 | ||
142 | - .. row 1 | |
143 | ||
144 | - Bits 0-2 | |
145 | ||
146 | - Block (aka offset) of the received data. | |
147 | ||
148 | - .. row 2 | |
149 | ||
150 | - Bits 3-5 | |
151 | ||
152 | - Deprecated. Currently identical to bits 0-2. Do not use these | |
0579e6e3 | 153 | bits. |
5377d91f MH |
154 | |
155 | - .. row 3 | |
156 | ||
157 | - Bit 6 | |
158 | ||
159 | - Corrected bit. Indicates that an error was corrected for this data | |
0579e6e3 | 160 | block. |
5377d91f MH |
161 | |
162 | - .. row 4 | |
163 | ||
164 | - Bit 7 | |
165 | ||
166 | - Error bit. Indicates that an uncorrectable error occurred during | |
0579e6e3 | 167 | reception of this block. |
5377d91f MH |
168 | |
169 | ||
170 | ||
171 | .. _v4l2-rds-block-codes: | |
172 | ||
352ca7e7 | 173 | .. tabularcolumns:: |p{5.6cm}|p{2.0cm}|p{1.5cm}|p{7.0cm}| |
5bd4bb78 | 174 | |
5377d91f MH |
175 | .. flat-table:: Block defines |
176 | :header-rows: 0 | |
177 | :stub-columns: 0 | |
178 | :widths: 1 1 1 5 | |
179 | ||
180 | ||
181 | - .. row 1 | |
182 | ||
183 | - V4L2_RDS_BLOCK_MSK | |
184 | ||
0579e6e3 | 185 | - |
5377d91f MH |
186 | - 7 |
187 | ||
188 | - Mask for bits 0-2 to get the block ID. | |
189 | ||
190 | - .. row 2 | |
191 | ||
192 | - V4L2_RDS_BLOCK_A | |
193 | ||
0579e6e3 | 194 | - |
5377d91f MH |
195 | - 0 |
196 | ||
197 | - Block A. | |
198 | ||
199 | - .. row 3 | |
200 | ||
201 | - V4L2_RDS_BLOCK_B | |
202 | ||
0579e6e3 | 203 | - |
5377d91f MH |
204 | - 1 |
205 | ||
206 | - Block B. | |
207 | ||
208 | - .. row 4 | |
209 | ||
210 | - V4L2_RDS_BLOCK_C | |
211 | ||
0579e6e3 | 212 | - |
5377d91f MH |
213 | - 2 |
214 | ||
215 | - Block C. | |
216 | ||
217 | - .. row 5 | |
218 | ||
219 | - V4L2_RDS_BLOCK_D | |
220 | ||
0579e6e3 | 221 | - |
5377d91f MH |
222 | - 3 |
223 | ||
224 | - Block D. | |
225 | ||
226 | - .. row 6 | |
227 | ||
228 | - V4L2_RDS_BLOCK_C_ALT | |
229 | ||
0579e6e3 | 230 | - |
5377d91f MH |
231 | - 4 |
232 | ||
233 | - Block C'. | |
234 | ||
235 | - .. row 7 | |
236 | ||
237 | - V4L2_RDS_BLOCK_INVALID | |
238 | ||
239 | - read-only | |
240 | ||
241 | - 7 | |
242 | ||
243 | - An invalid block. | |
244 | ||
245 | - .. row 8 | |
246 | ||
247 | - V4L2_RDS_BLOCK_CORRECTED | |
248 | ||
249 | - read-only | |
250 | ||
251 | - 0x40 | |
252 | ||
253 | - A bit error was detected but corrected. | |
254 | ||
255 | - .. row 9 | |
256 | ||
257 | - V4L2_RDS_BLOCK_ERROR | |
258 | ||
259 | - read-only | |
260 | ||
261 | - 0x80 | |
262 | ||
263 | - An uncorrectable error occurred. |