From: Jens Steinhauser Date: Tue, 8 Jul 2014 20:15:30 +0000 (+0200) Subject: Add nRF24L01(+) protocol decoder. X-Git-Tag: libsigrokdecode-0.4.0~209 X-Git-Url: https://sigrok.org/gitweb/?p=libsigrokdecode.git;a=commitdiff_plain;h=0e501c70cf26f208d7e523b7fe737d0e8d565109 Add nRF24L01(+) protocol decoder. --- diff --git a/decoders/nrf24l01/__init__.py b/decoders/nrf24l01/__init__.py new file mode 100644 index 0000000..4681abf --- /dev/null +++ b/decoders/nrf24l01/__init__.py @@ -0,0 +1,30 @@ +## +## This file is part of the libsigrokdecode project. +## +## Copyright (C) 2014 Jens Steinhauser +## +## This program is free software; you can redistribute it and/or modify +## it under the terms of the GNU General Public License as published by +## the Free Software Foundation; either version 2 of the License, or +## (at your option) any later version. +## +## This program is distributed in the hope that it will be useful, +## but WITHOUT ANY WARRANTY; without even the implied warranty of +## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +## GNU General Public License for more details. +## +## You should have received a copy of the GNU General Public License +## along with this program; if not, write to the Free Software +## Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA +## + +''' +This decoder stacks on top of the 'spi' PD and decodes the protocol spoken +by the Nordic Semiconductor nRF24L01 and nRF24L01+ 2.4GHz transceiver chips. + +Details: +http://www.nordicsemi.com/eng/Products/2.4GHz-RF/nRF24L01 +http://www.nordicsemi.com/eng/Products/2.4GHz-RF/nRF24L01P +''' + +from .pd import * diff --git a/decoders/nrf24l01/pd.py b/decoders/nrf24l01/pd.py new file mode 100644 index 0000000..39a6808 --- /dev/null +++ b/decoders/nrf24l01/pd.py @@ -0,0 +1,300 @@ +## +## This file is part of the libsigrokdecode project. +## +## Copyright (C) 2014 Jens Steinhauser +## +## This program is free software; you can redistribute it and/or modify +## it under the terms of the GNU General Public License as published by +## the Free Software Foundation; either version 2 of the License, or +## (at your option) any later version. +## +## This program is distributed in the hope that it will be useful, +## but WITHOUT ANY WARRANTY; without even the implied warranty of +## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +## GNU General Public License for more details. +## +## You should have received a copy of the GNU General Public License +## along with this program; if not, write to the Free Software +## Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA +## + +import sigrokdecode as srd + +class MissingDataError(Exception): + pass + +regs = { +# addr: ('name', size) + 0x00: ('CONFIG', 1), + 0x01: ('EN_AA', 1), + 0x02: ('EN_RXADDR', 1), + 0x03: ('SETUP_AW', 1), + 0x04: ('SETUP_RETR', 1), + 0x05: ('RF_CH', 1), + 0x06: ('RF_SETUP', 1), + 0x07: ('STATUS', 1), + 0x08: ('OBSERVE_TX', 1), + 0x09: ('RPD', 1), + 0x0a: ('RX_ADDR_P0', 5), + 0x0b: ('RX_ADDR_P1', 5), + 0x0c: ('RX_ADDR_P2', 1), + 0x0d: ('RX_ADDR_P3', 1), + 0x0e: ('RX_ADDR_P4', 1), + 0x0f: ('RX_ADDR_P5', 1), + 0x10: ('TX_ADDR', 5), + 0x11: ('RX_PW_P0', 1), + 0x12: ('RX_PW_P1', 1), + 0x13: ('RX_PW_P2', 1), + 0x14: ('RX_PW_P3', 1), + 0x15: ('RX_PW_P4', 1), + 0x16: ('RX_PW_P5', 1), + 0x17: ('FIFO_STATUS', 1), + 0x1c: ('DYNPD', 1), + 0x1d: ('FEATURE', 1) +} + +class Decoder(srd.Decoder): + api_version = 2 + id = 'nrf24l01' + name = 'NRF24L01(+)' + longname = 'Nordic Semiconductor nRF24L01/nRF24L01+' + desc = '2.4 GHz transceiver chip.' + license = 'gplv2+' + inputs = ['spi'] + outputs = ['nrf24l01'] + annotations = ( + # sent from the host to the chip + ('cmd', 'Commands send to the device.'), + ('tx-data', 'Payload send to the device.'), + + # returned by the chip + ('register', 'Registers read from the device.'), + ('rx-data', 'Payload read from the device.'), + + ('warning', 'Warnings'), + ) + ann_cmd = 0 + ann_tx = 1 + ann_reg = 2 + ann_rx = 3 + ann_warn = 4 + annotation_rows = ( + ('commands', 'Commands', (ann_cmd, ann_tx)), + ('responses', 'Responses', (ann_reg, ann_rx)), + ('warnings', 'Warnings', (ann_warn,)), + ) + + def __init__(self, **kwargs): + self.next() + + def start(self): + self.out_ann = self.register(srd.OUTPUT_ANN) + + def warn(self, pos, msg): + '''Put a warning message 'msg' at 'pos'.''' + self.put(pos[0], pos[1], self.out_ann, [self.ann_warn, [msg]]) + + def putp(self, pos, ann, msg): + '''Put an annotation message 'msg' at 'pos'.''' + self.put(pos[0], pos[1], self.out_ann, [ann, [msg]]) + + def next(self): + '''Resets the decoder after a complete command was decoded.''' + # 'True' for the first byte after CS went low + self.first = True + + # the current command, and the minimum and maximum number + # of data bytes to follow + self.cmd = None + self.min = 0 + self.max = 0 + + # used to collect the bytes after the command byte + # (and the start/end sample number) + self.mb = [] + self.mb_s = -1 + self.mb_e = -1 + + def mosi_bytes(self): + '''Returns the collected MOSI bytes of a multi byte command.''' + return [b[0] for b in self.mb] + + def miso_bytes(self): + '''Returns the collected MISO bytes of a multi byte command.''' + return [b[1] for b in self.mb] + + def decode_command(self, pos, b): + '''Decodes the command byte 'b' at position 'pos' and prepares + the decoding of the following data bytes.''' + c = self.parse_command(b) + if c == None: + self.warn(pos, 'unknown command') + return + + self.cmd, self.dat, self.min, self.max = c + + if self.cmd in ('W_REGISTER', 'ACTIVATE'): + # don't output anything now, the command is merged with + # the data bytes following it + self.mb_s = pos[0] + else: + self.putp(pos, self.ann_cmd, self.format_command()) + + def format_command(self): + '''Returns the label for the current command.''' + if self.cmd == 'R_REGISTER': + reg = regs[self.dat][0] if self.dat in regs else 'unknown register' + return 'Cmd. R_REGISTER "{}"'.format(reg) + else: + return 'Cmd. {}'.format(self.cmd) + + def parse_command(self, b): + '''Parses the command byte. + + Returns a tuple consisting of: + - the name of the command + - additional data needed to dissect the following bytes + - minimum number of following bytes + - maximum number of following bytes + ''' + + if (b & 0xe0) in (0b00000000, 0b00100000): + c = 'R_REGISTER' if not (b & 0xe0) else 'W_REGISTER' + d = b & 0x1f + m = regs[d][1] if d in regs else 1 + return (c, d, 1, m) + if b == 0b01010000: + # nRF24L01 only + return ('ACTIVATE', None, 1, 1) + if b == 0b01100001: + return ('R_RX_PAYLOAD', None, 1, 32) + if b == 0b01100000: + return ('R_RX_PL_WID', None, 1, 1) + if b == 0b10100000: + return ('W_TX_PAYLOAD', None, 1, 32) + if b == 0b10110000: + return ('W_TX_PAYLOAD_NOACK', None, 1, 32) + if (b & 0xf8) == 0b10101000: + return ('W_ACK_PAYLOAD', b & 0x07, 1, 32) + if b == 0b11100001: + return ('FLUSH_TX', None, 0, 0) + if b == 0b11100010: + return ('FLUSH_RX', None, 0, 0) + if b == 0b11100011: + return ('REUSE_TX_PL', None, 0, 0) + if b == 0b11111111: + return ('NOP', None, 0, 0) + + def decode_register(self, pos, ann, regid, data): + '''Decodes a register. + + pos -- start and end sample numbers of the register + ann -- is the annotation number that is used to output the register. + regid -- may be either an integer used as a key for the 'regs' + dictionary, or a string directly containing a register name.' + data -- is the register content. + ''' + + if type(regid) == int: + # get the name of the register + if regid not in regs: + self.warn(pos, 'unknown register') + return + + name = regs[regid][0] + else: + name = regid + + # multi byte register come LSByte first + data = reversed(data) + + if self.cmd == 'W_REGISTER' and ann == self.ann_cmd: + # the 'W_REGISTER' command is merged with the following byte(s) + label = '{}: {}'.format(self.format_command(), name) + else: + label = 'Reg. {}'.format(name) + + self.decode_mb_data(pos, ann, data, label) + + def decode_mb_data(self, pos, ann, data, label, escape_all=True): + '''Decodes the data bytes 'data' of a multibyte command at position + 'pos'. The decoded data is prefixed with 'label'. If 'excape_all' is + True, all data bytes are escaped as hex codes.''' + + def escape(b): + c = chr(b) + if escape_all or not str.isprintable(c): + return '\\x{:02X}'.format(b) + return c + + data = ''.join([escape(b) for b in data]) + text = '{} = "{}"'.format(label, data) + self.putp(pos, ann, text) + + def finish_command(self, pos): + '''Decodes the remaining data bytes at position 'pos'.''' + + if self.cmd == 'R_REGISTER': + self.decode_register(pos, self.ann_reg, + self.dat, self.miso_bytes()); + elif self.cmd == 'W_REGISTER': + self.decode_register(pos, self.ann_cmd, + self.dat, self.mosi_bytes()); + elif self.cmd == 'R_RX_PAYLOAD': + self.decode_mb_data(pos, self.ann_rx, + self.miso_bytes(), 'RX payload', False) + elif (self.cmd == 'W_TX_PAYLOAD' or + self.cmd == 'W_TX_PAYLOAD_NOACK'): + self.decode_mb_data(pos, self.ann_tx, + self.mosi_bytes(), 'TX payload', False) + elif self.cmd == 'W_ACK_PAYLOAD': + lbl = 'ACK payload for pipe {}'.format(self.dat) + self.decode_mb_data(pos, self.ann_tx, + self.mosi_bytes(), lbl, False) + elif self.cmd == 'R_RX_PL_WID': + msg = 'Payload width = {}'.format(self.mb[0][1]) + self.putp(pos, self.ann_reg, msg) + elif self.cmd == 'ACTIVATE': + self.putp(pos, self.ann_cmd, self.format_command()) + if self.mosi_bytes()[0] != 0x73: + self.warn(pos, 'wrong data for "ACTIVATE" command') + + def decode(self, ss, es, data): + ptype, data1, data2 = data + + if ptype == 'CS-CHANGE': + if data1 == 0 and data2 == 1: + # rising edge, the complete command is transmitted, process + # the bytes that were send after the command byte + if self.cmd: + # check if we got the minimum number of data bytes + # after the command byte + if len(self.mb) < self.min: + self.warn((ss, ss), 'missing data bytes') + elif self.mb: + self.finish_command((self.mb_s, self.mb_e)) + + self.next() + elif ptype == 'DATA': + mosi = data1 + miso = data2 + pos = (ss, es) + + if miso == None or mosi == None: + raise MissingDataError('Both MISO and MOSI pins required.') + + if self.first: + self.first = False + # first MOSI byte is always the command + self.decode_command(pos, mosi) + # first MISO byte is always the status register + self.decode_register(pos, self.ann_reg, 'STATUS', [miso]) + else: + if not self.cmd or len(self.mb) >= self.max: + self.warn(pos, 'excess byte') + else: + # collect the bytes after the command byte + if self.mb_s == -1: + self.mb_s = ss + self.mb_e = es + self.mb.append((mosi, miso)) diff --git a/decoders/nrf24l01/test/nrf24l01_activate_cmd.output b/decoders/nrf24l01/test/nrf24l01_activate_cmd.output new file mode 100644 index 0000000..4d5c33b --- /dev/null +++ b/decoders/nrf24l01/test/nrf24l01_activate_cmd.output @@ -0,0 +1,2 @@ +3-36 nrf24l01: cmd: "Cmd. ACTIVATE" +41-74 nrf24l01: cmd: "Cmd. ACTIVATE" diff --git a/decoders/nrf24l01/test/nrf24l01_activate_warning.output b/decoders/nrf24l01/test/nrf24l01_activate_warning.output new file mode 100644 index 0000000..64451ff --- /dev/null +++ b/decoders/nrf24l01/test/nrf24l01_activate_warning.output @@ -0,0 +1 @@ +41-74 nrf24l01: warning: "wrong data for "ACTIVATE" command" diff --git a/decoders/nrf24l01/test/nrf24l01_communication_rx.output b/decoders/nrf24l01/test/nrf24l01_communication_rx.output new file mode 100644 index 0000000..4de4875 --- /dev/null +++ b/decoders/nrf24l01/test/nrf24l01_communication_rx.output @@ -0,0 +1,6 @@ +378689-378962 nrf24l01: rx-data: "RX payload = "message #0"" +499905-500178 nrf24l01: rx-data: "RX payload = "message #1"" +621693-621966 nrf24l01: rx-data: "RX payload = "message #2"" +738358-738631 nrf24l01: rx-data: "RX payload = "message #3"" +867005-867279 nrf24l01: rx-data: "RX payload = "message #4"" +986889-987163 nrf24l01: rx-data: "RX payload = "message #5"" diff --git a/decoders/nrf24l01/test/nrf24l01_communication_tx.output b/decoders/nrf24l01/test/nrf24l01_communication_tx.output new file mode 100644 index 0000000..45ac8d5 --- /dev/null +++ b/decoders/nrf24l01/test/nrf24l01_communication_tx.output @@ -0,0 +1,10 @@ +366098-366374 nrf24l01: tx-data: "TX payload = "message #0"" +488110-488387 nrf24l01: tx-data: "TX payload = "message #1"" +610131-610408 nrf24l01: tx-data: "TX payload = "message #2"" +732181-732458 nrf24l01: tx-data: "TX payload = "message #3"" +854221-854498 nrf24l01: tx-data: "TX payload = "message #4"" +976255-976531 nrf24l01: tx-data: "TX payload = "message #5"" +1098294-1098570 nrf24l01: tx-data: "TX payload = "message #6"" +1220322-1220597 nrf24l01: tx-data: "TX payload = "message #7"" +1342302-1342579 nrf24l01: tx-data: "TX payload = "message #8"" +1464309-1464586 nrf24l01: tx-data: "TX payload = "message #9"" diff --git a/decoders/nrf24l01/test/nrf24l01_excess_bytes_warning.output b/decoders/nrf24l01/test/nrf24l01_excess_bytes_warning.output new file mode 100644 index 0000000..7f7b9bd --- /dev/null +++ b/decoders/nrf24l01/test/nrf24l01_excess_bytes_warning.output @@ -0,0 +1,7 @@ +75-91 nrf24l01: warning: "excess byte" +130-146 nrf24l01: warning: "excess byte" +185-201 nrf24l01: warning: "excess byte" +202-218 nrf24l01: warning: "excess byte" +325-341 nrf24l01: warning: "excess byte" +380-396 nrf24l01: warning: "excess byte" +962-978 nrf24l01: warning: "excess byte" diff --git a/decoders/nrf24l01/test/nrf24l01_misc_cmd.output b/decoders/nrf24l01/test/nrf24l01_misc_cmd.output new file mode 100644 index 0000000..015031e --- /dev/null +++ b/decoders/nrf24l01/test/nrf24l01_misc_cmd.output @@ -0,0 +1,5 @@ +3-19 nrf24l01: cmd: "Cmd. REUSE_TX_PL" +24-40 nrf24l01: cmd: "Cmd. R_RX_PL_WID" +62-78 nrf24l01: cmd: "Cmd. R_RX_PL_WID" +83-99 nrf24l01: cmd: "Cmd. R_RX_PL_WID" +138-154 nrf24l01: cmd: "Cmd. W_ACK_PAYLOAD" diff --git a/decoders/nrf24l01/test/nrf24l01_misc_register.output b/decoders/nrf24l01/test/nrf24l01_misc_register.output new file mode 100644 index 0000000..394846d --- /dev/null +++ b/decoders/nrf24l01/test/nrf24l01_misc_register.output @@ -0,0 +1,7 @@ +3-19 nrf24l01: register: "Reg. STATUS = "\x00"" +24-40 nrf24l01: register: "Reg. STATUS = "\x00"" +41-57 nrf24l01: register: "Payload width = 9" +62-78 nrf24l01: register: "Reg. STATUS = "\x00"" +83-99 nrf24l01: register: "Reg. STATUS = "\x00"" +100-116 nrf24l01: register: "Payload width = 9" +138-154 nrf24l01: register: "Reg. STATUS = "\x00"" diff --git a/decoders/nrf24l01/test/nrf24l01_misc_tx_data.output b/decoders/nrf24l01/test/nrf24l01_misc_tx_data.output new file mode 100644 index 0000000..e28d662 --- /dev/null +++ b/decoders/nrf24l01/test/nrf24l01_misc_tx_data.output @@ -0,0 +1 @@ +155-426 nrf24l01: tx-data: "ACK payload for pipe 1 = "\x00\x01\x02\x03\x04abcdef\x00\x01\x02\x03\x04"" diff --git a/decoders/nrf24l01/test/nrf24l01_misc_warning.output b/decoders/nrf24l01/test/nrf24l01_misc_warning.output new file mode 100644 index 0000000..4ec511e --- /dev/null +++ b/decoders/nrf24l01/test/nrf24l01_misc_warning.output @@ -0,0 +1,2 @@ +79-79 nrf24l01: warning: "missing data bytes" +117-133 nrf24l01: warning: "excess byte" diff --git a/decoders/nrf24l01/test/nrf24l01_missing_bytes_warning.output b/decoders/nrf24l01/test/nrf24l01_missing_bytes_warning.output new file mode 100644 index 0000000..e1b6344 --- /dev/null +++ b/decoders/nrf24l01/test/nrf24l01_missing_bytes_warning.output @@ -0,0 +1,2 @@ +20-20 nrf24l01: warning: "missing data bytes" +41-41 nrf24l01: warning: "missing data bytes" diff --git a/decoders/nrf24l01/test/nrf24l01_no_command_register.output b/decoders/nrf24l01/test/nrf24l01_no_command_register.output new file mode 100644 index 0000000..2269878 --- /dev/null +++ b/decoders/nrf24l01/test/nrf24l01_no_command_register.output @@ -0,0 +1,4 @@ +11-27 nrf24l01: register: "Reg. STATUS = "\x00"" +28-44 nrf24l01: register: "Reg. CONFIG = "\x00"" +53-69 nrf24l01: register: "Reg. STATUS = "\x00"" +70-86 nrf24l01: register: "Reg. CONFIG = "\x00"" diff --git a/decoders/nrf24l01/test/nrf24l01_rx.output b/decoders/nrf24l01/test/nrf24l01_rx.output new file mode 100644 index 0000000..e04132e --- /dev/null +++ b/decoders/nrf24l01/test/nrf24l01_rx.output @@ -0,0 +1 @@ +378689-378962 nrf24l01: rx-data: "RX payload = "message #0"" diff --git a/decoders/nrf24l01/test/nrf24l01_unknown_command_warning.output b/decoders/nrf24l01/test/nrf24l01_unknown_command_warning.output new file mode 100644 index 0000000..e229fe8 --- /dev/null +++ b/decoders/nrf24l01/test/nrf24l01_unknown_command_warning.output @@ -0,0 +1,2 @@ +41-57 nrf24l01: warning: "unknown command" +58-74 nrf24l01: warning: "excess byte" diff --git a/decoders/nrf24l01/test/nrf24l01_unknown_register_warning.output b/decoders/nrf24l01/test/nrf24l01_unknown_register_warning.output new file mode 100644 index 0000000..fcb1d89 --- /dev/null +++ b/decoders/nrf24l01/test/nrf24l01_unknown_register_warning.output @@ -0,0 +1 @@ +20-36 nrf24l01: warning: "unknown register" diff --git a/decoders/nrf24l01/test/test.conf b/decoders/nrf24l01/test/test.conf new file mode 100644 index 0000000..8b6d77b --- /dev/null +++ b/decoders/nrf24l01/test/test.conf @@ -0,0 +1,80 @@ +test activate + protocol-decoder spi channel cs=0 channel clk=1 channel mosi=2 channel miso=3 + protocol-decoder nrf24l01 + stack spi nrf24l01 + input spi/nrf24l01/nrf24l01-test-activate.sr + output nrf24l01 annotation class cmd match nrf24l01_activate_cmd.output + output nrf24l01 annotation class warning match nrf24l01_activate_warning.output + +test communication-rx + protocol-decoder spi channel cs=0 channel clk=1 channel mosi=2 channel miso=3 + protocol-decoder nrf24l01 + stack spi nrf24l01 + input spi/nrf24l01/nrf24l01-communication-rx.sr + output nrf24l01 annotation class rx-data match nrf24l01_communication_rx.output + +test communication-tx + protocol-decoder spi channel cs=0 channel clk=1 channel mosi=2 channel miso=3 + protocol-decoder nrf24l01 + stack spi nrf24l01 + input spi/nrf24l01/nrf24l01-communication-tx.sr + output nrf24l01 annotation class tx-data match nrf24l01_communication_tx.output + +test excess-bytes + protocol-decoder spi channel cs=0 channel clk=1 channel mosi=2 channel miso=3 + protocol-decoder nrf24l01 + stack spi nrf24l01 + input spi/nrf24l01/nrf24l01-test-excess-bytes.sr + output nrf24l01 annotation class warning match nrf24l01_excess_bytes_warning.output + +test misc + protocol-decoder spi channel cs=0 channel clk=1 channel mosi=2 channel miso=3 + protocol-decoder nrf24l01 + stack spi nrf24l01 + input spi/nrf24l01/nrf24l01-test-misc.sr + output nrf24l01 annotation class cmd match nrf24l01_misc_cmd.output + output nrf24l01 annotation class tx-data match nrf24l01_misc_tx_data.output + output nrf24l01 annotation class register match nrf24l01_misc_register.output + output nrf24l01 annotation class warning match nrf24l01_misc_warning.output + +test missing-bytes + protocol-decoder spi channel cs=0 channel clk=1 channel mosi=2 channel miso=3 + protocol-decoder nrf24l01 + stack spi nrf24l01 + input spi/nrf24l01/nrf24l01-test-missing-bytes.sr + output nrf24l01 annotation class warning match nrf24l01_missing_bytes_warning.output + +test no-command + protocol-decoder spi channel cs=0 channel clk=1 channel mosi=2 channel miso=3 + protocol-decoder nrf24l01 + stack spi nrf24l01 + input spi/nrf24l01/nrf24l01-test-no-command.sr + output nrf24l01 annotation class register match nrf24l01_no_command_register.output + +test no-mosi + protocol-decoder spi channel cs=0 channel clk=1 channel miso=3 + protocol-decoder nrf24l01 + stack spi nrf24l01 + input spi/nrf24l01/nrf24l01-test-no-command.sr + output nrf24l01 exception match MissingDataError + +test no-miso + protocol-decoder spi channel cs=0 channel clk=1 channel mosi=2 + protocol-decoder nrf24l01 + stack spi nrf24l01 + input spi/nrf24l01/nrf24l01-test-no-command.sr + output nrf24l01 exception match MissingDataError + +test unknown-command + protocol-decoder spi channel cs=0 channel clk=1 channel mosi=2 channel miso=3 + protocol-decoder nrf24l01 + stack spi nrf24l01 + input spi/nrf24l01/nrf24l01-test-unknown-command.sr + output nrf24l01 annotation class warning match nrf24l01_unknown_command_warning.output + +test unknown-register + protocol-decoder spi channel cs=0 channel clk=1 channel mosi=2 channel miso=3 + protocol-decoder nrf24l01 + stack spi nrf24l01 + input spi/nrf24l01/nrf24l01-test-unknown-register.sr + output nrf24l01 annotation class warning match nrf24l01_unknown_register_warning.output