2 ## This file is part of the libsigrokdecode project.
4 ## Copyright (C) 2016 Fabian J. Stumpf <sigrok@fabianstumpf.de>
5 ## Copyright (C) 2019-2020 Gerhard Sittig <gerhard.sittig@gmx.net>
7 ## This program is free software; you can redistribute it and/or modify
8 ## it under the terms of the GNU General Public License as published by
9 ## the Free Software Foundation; either version 2 of the License, or
10 ## (at your option) any later version.
12 ## This program is distributed in the hope that it will be useful,
13 ## but WITHOUT ANY WARRANTY; without even the implied warranty of
14 ## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15 ## GNU General Public License for more details.
17 ## You should have received a copy of the GNU General Public License
18 ## along with this program; if not, see <http://www.gnu.org/licenses/>.
27 This is the list of <ptype> codes and their respective <pdata> values:
28 - 'PACKET': The data is a list of tuples with the bytes' start and end
29 positions as well as a byte value and a validity flag. This output
30 represents a DMX packet. The sample numbers span the range beginning
31 at the start of the start code and ending at the end of the last data
32 byte in the packet. The start code value resides at index 0.
34 Developer notes on the DMX512 protocol:
36 See Wikipedia for an overview:
37 https://en.wikipedia.org/wiki/DMX512#Electrical (physics, transport)
38 https://en.wikipedia.org/wiki/DMX512#Protocol (UART frames, DMX frames)
39 RS-485 transport, differential thus either polarity (needs user spec)
40 8n2 UART frames at 250kbps, BREAK to start a new DMX frame
41 slot 0 carries start code, slot 1 up to 512 max carry data for peripherals
42 start code 0 for "boring lights", non-zero start code for extensions.
45 - Cover more DMX packet types beyond start code 0x00 (standard). See
46 https://en.wikipedia.org/wiki/DMX512#Protocol for a list (0x17 text,
47 0xcc RDM, 0xcf sysinfo) and a reference to the ESTA database. These
48 can either get added here or can get implemented in a stacked decoder.
49 - Run on more captures as these become available. Verify the min/max
50 BREAK, MARK, and RESET to RESET period checks. Add more conditions that
51 are worth checking to determine the health of the bus, see the (German)
52 http://www.soundlight.de/techtips/dmx512/dmx2000a.htm article for ideas.
53 - Is there a more user friendly way of having the DMX512 decoder configure
54 the UART decoder's parameters? Currently users need to setup the polarity
55 (which is acceptable, and an essential feature), but also the bitrate and
56 frame format (which may or may not be considered acceptable).
57 - (Not a DMX512 decoder TODO item) Current UART decoder implementation does
58 not handle two STOP bits, but DMX512 will transparently benefit when UART
59 gets adjusted. Until then the second STOP bit will be mistaken for a MARK
60 but that's just cosmetics, available data gets interpreted correctly.
63 import sigrokdecode as srd
66 BREAK, MAB, INTERFRAME, INTERPACKET, STARTCODE, DATABYTE, CHANNEL_DATA, \
67 SLOT_DATA, RESET, WARN, ERROR = range(11)
69 class Decoder(srd.Decoder):
73 longname = 'Digital MultipleX 512'
74 desc = 'Digital MultipleX 512 (DMX512) lighting protocol.'
78 tags = ['Embedded/industrial', 'Lighting']
80 {'id': 'min_break', 'desc': 'Minimum BREAK length (us)', 'default': 88},
81 {'id': 'max_mark', 'desc': 'Maximum MARK length (us)', 'default': 1000000},
82 {'id': 'min_break_break', 'desc': 'Minimum BREAK to BREAK interval (us)',
84 {'id': 'max_reset_reset', 'desc': 'Maximum RESET to RESET interval (us)',
86 {'id': 'show_zero', 'desc': 'Display all-zero set-point values',
87 'default': 'no', 'values': ('yes', 'no')},
88 {'id': 'format', 'desc': 'Data format', 'default': 'dec',
89 'values': ('dec', 'hex', 'bin')},
92 # Lowest layer (above UART): BREAK MARK ( FRAME [MARK] )*
93 # with MARK being after-break or inter-frame or inter-packet.
95 ('mab', 'Mark after break'),
96 ('interframe', 'Interframe'),
97 ('interpacket', 'Interpacket'),
98 # Next layer: STARTCODE ( DATABYTE )*
99 ('startcode', 'Start code'),
100 ('databyte', 'Data byte'),
101 # Next layer: CHANNEL or SLOT values
102 ('chan_data', 'Channel data'),
103 ('slot_data', 'Slot data'),
105 ('reset', 'Reset sequence'),
106 # Warnings and errors.
107 ('warning', 'Warning'),
111 ('dmx_fields', 'Fields', (Ann.BREAK, Ann.MAB,
112 Ann.STARTCODE, Ann.INTERFRAME,
113 Ann.DATABYTE, Ann.INTERPACKET)),
114 ('chans_data', 'Channels data', (Ann.CHANNEL_DATA,)),
115 ('slots_data', 'Slots data', (Ann.SLOT_DATA,)),
116 ('resets', 'Reset sequences', (Ann.RESET,)),
117 ('warnings', 'Warnings', (Ann.WARN,)),
118 ('errors', 'Errors', (Ann.ERROR,)),
125 self.samplerate = None
126 self.samples_per_usec = None
127 self.last_reset = None
128 self.last_break = None
131 self.last_frame = None
132 self.start_code = None
135 self.out_ann = self.register(srd.OUTPUT_ANN)
136 self.out_python = self.register(srd.OUTPUT_PYTHON)
138 def metadata(self, key, value):
139 if key == srd.SRD_CONF_SAMPLERATE:
140 self.samplerate = value
141 self.samples_per_usec = value / 1000000
143 def have_samplerate(self):
144 return bool(self.samplerate)
146 def samples_to_usecs(self, count):
147 return count / self.samples_per_usec
149 def putg(self, ss, es, data):
150 self.put(ss, es, self.out_ann, data)
152 def putpy(self, ss, es, data):
153 self.put(ss, es, self.out_python, data)
155 def format_value(self, v):
156 fmt = self.options['format']
158 return '{:d}'.format(v)
160 return '{:02X}'.format(v)
162 return '{:08b}'.format(v)
163 return '{}'.format(v)
165 def flush_packet(self):
167 ss, es = self.packet[0][0], self.packet[-1][1]
168 self.putpy(ss, es, ['PACKET', self.packet])
171 def flush_reset(self, ss, es):
172 if ss is not None and es is not None:
173 self.putg(ss, es, [Ann.RESET, ['RESET SEQUENCE', 'RESET', 'R']])
174 if self.last_reset and self.have_samplerate():
175 duration = self.samples_to_usecs(es - self.last_reset)
176 if duration > self.options['max_reset_reset']:
177 txts = ['Excessive RESET to RESET interval', 'RESET to RESET', 'RESET']
178 self.putg(self.last_reset, es, [Ann.WARN, txts])
181 def flush_break(self, ss, es):
182 self.putg(ss, es, [Ann.BREAK, ['BREAK', 'B']])
183 if self.have_samplerate():
184 duration = self.samples_to_usecs(es - ss)
185 if duration < self.options['min_break']:
186 txts = ['Short BREAK period', 'Short BREAK', 'BREAK']
187 self.putg(ss, es, [Ann.WARN, txts])
189 duration = self.samples_to_usecs(ss - self.last_break)
190 if duration < self.options['min_break_break']:
191 txts = ['Short BREAK to BREAK interval', 'Short BREAK to BREAK', 'BREAK']
192 self.putg(ss, es, [Ann.WARN, txts])
196 def flush_mark(self, ss, es, is_mab = False, is_if = False, is_ip = False):
197 '''Handle several kinds of MARK conditions.'''
199 if ss is None or es is None or ss >= es:
204 txts = ['MARK AFTER BREAK', 'MAB']
207 txts = ['INTER FRAME', 'IF']
209 ann = Ann.INTERPACKET
210 txts = ['INTER PACKET', 'IP']
213 self.putg(ss, es, [ann, txts])
215 if self.have_samplerate():
216 duration = self.samples_to_usecs(es - ss)
217 if duration > self.options['max_mark']:
218 txts = ['Excessive MARK length', 'MARK length', 'MARK']
219 self.putg(ss, es, [Ann.ERROR, txts])
221 def flush_frame(self, ss, es, value, valid):
222 '''Handle UART frame content. Accumulate DMX packet.'''
225 txts = ['Invalid frame', 'Frame']
226 self.putg(ss, es, [Ann.ERROR, txts])
230 # Cease packet inspection before first BREAK.
231 if not self.last_break:
234 # Accumulate the sequence of bytes for the current DMX frame.
235 # Emit the annotation at the "DMX fields" level.
236 is_start = self.packet is None
239 slot_nr = len(self.packet)
240 item = (ss, es, value, valid)
241 self.packet.append(item)
243 # Slot 0, the start code. Determines the DMX frame type.
244 self.start_code = value
246 val_text = self.format_value(value)
248 'STARTCODE {}'.format(val_text),
249 'START {}'.format(val_text),
250 '{}'.format(val_text),
253 # Slot 1+, the payload bytes.
255 val_text = self.format_value(value)
257 'DATABYTE {:d}: {}'.format(slot_nr, val_text),
258 'DATA {:d}: {}'.format(slot_nr, val_text),
259 'DATA {}'.format(val_text),
260 '{}'.format(val_text),
262 self.putg(ss, es, [ann, txts])
264 # Tell channel data for peripherals from arbitrary slot values.
265 # Can get extended for other start code types in case protocol
266 # extensions are handled here and not in stacked decoders.
269 elif self.start_code == 0:
270 # Start code was 0. Slots carry values for channels.
271 # Optionally suppress zero-values to make used channels
272 # stand out, to help users focus their attention.
273 ann = Ann.CHANNEL_DATA
274 if value == 0 and self.options['show_zero'] == 'no':
277 val_text = self.format_value(value)
279 'CHANNEL {:d}: {}'.format(slot_nr, val_text),
280 'CH {:d}: {}'.format(slot_nr, val_text),
281 'CH {}'.format(val_text),
282 '{}'.format(val_text),
285 # Unhandled start code. Provide "anonymous" values.
287 val_text = self.format_value(value)
289 'SLOT {:d}: {}'.format(slot_nr, val_text),
290 'SL {:d}: {}'.format(slot_nr, val_text),
291 'SL {}'.format(val_text),
292 '{}'.format(val_text),
295 self.putg(ss, es, [ann, txts])
297 if is_start and value == 0:
298 self.flush_reset(self.last_break, es)
300 def handle_break(self, ss, es):
301 '''Handle UART BREAK conditions.'''
303 # Check the last frame before BREAK if one was queued. It could
304 # have been "invalid" since the STOP bit check failed. If there
305 # is an invalid frame which happens to start at the start of the
306 # BREAK condition, then discard it. Otherwise flush its output.
307 last_frame = self.last_frame
308 self.last_frame = None
309 frame_invalid = last_frame and not last_frame[3]
310 frame_zero_data = last_frame and last_frame[2] == 0
311 frame_is_break = last_frame and last_frame[0] == ss
312 if frame_invalid and frame_zero_data and frame_is_break:
314 if last_frame is not None:
315 self.flush_frame(*last_frame)
317 # Handle inter-packet MARK (works for zero length, too).
318 self.flush_mark(self.last_es, ss, is_ip = True)
320 # Handle accumulated packets.
324 # Annotate the BREAK condition. Start accumulation of a packet.
325 self.flush_break(ss, es)
327 def handle_frame(self, ss, es, value, valid):
328 '''Handle UART data frames.'''
330 # Flush previously deferred frame (if available). Can't have been
331 # BREAK if another data frame follows.
332 last_frame = self.last_frame
333 self.last_frame = None
335 self.flush_frame(*last_frame)
337 # Handle inter-frame MARK (works for zero length, too).
338 is_mab = self.last_break and self.packet is None
340 self.flush_mark(self.last_es, ss, is_mab = is_mab, is_if = is_if)
342 # Defer handling of invalid frames, because they may start a new
343 # BREAK which we will only learn about much later. Immediately
344 # annotate valid frames.
346 self.flush_frame(ss, es, value, valid)
348 self.last_frame = (ss, es, value, valid)
350 def decode(self, ss, es, data):
351 # Lack of a sample rate in the input capture only disables the
352 # optional warnings about exceeded timespans here at the DMX512
353 # decoder level. That the lower layer UART decoder depends on a
354 # sample rate is handled there, and is not relevant here.
356 ptype, rxtx, pdata = data
358 self.handle_break(ss, es)
359 elif ptype == 'FRAME':
361 self.handle_frame(ss, es, value, valid)