Protocol decoder:numbers_and_state

From sigrok
Jump to navigation Jump to search
Numbers state mugshot.png
Name Numbers and state
Description Interpret bit patterns as different kinds of numbers (integer, float, enum)
Status supported
License GPLv2+
Source code decoders/numbers_and_state
Input logic
Output numbers_and_state

The Numbers and state decoder takes a set of logic input signals, and interprets their bit pattern according to user specs as either signed or unsigned integers, or floating point numbers. Users can specify external data files and have raw numbers mapped to user provided text strings. Which can help identify machine states, or locations along a code path, or RTOS tasks.


The decoder expects a set of data lines as input. Not connected bit positions are assumed to be low (0). Users can specify the number's total width in bits. This allows to grab just a few signals of a wider bus, and see if there is _some_ activity. Which can be useful when the acquisition device lacks spare channels for the full number.

An optional clock signal is supported. When connected, data gets sampled at rising, falling, or either edges. When the clock is not provided, data gets sampled when any of the data lines changes. Which can result in very short and rather many annotations for glitchy setups (like software bitbanged busses).


  • Clock edge: rising, falling, either
  • Total bits count: a user provided number, or automatic when 0 (derived from connected input signals)
  • Interpretation: unsigned, signed, fixpoint, fixsigned, ieee754, enum
  • Fraction bits count: a user provided number, can also be negative (then multiplies)
  • Enum to text map file: name of a Python or JSON file which maps integers to text strings
  • Number format: -, bin, oct, dec, hex

Enumerations are a special mode. A bit pattern is taken as a number which represents a state or condition. User provided map files can translate these numbers to display text. In addition the numbers are shown on individual rows, which results in a tabular presentation of e.g. state machine transitions, or RTOS task switches. The number of rows is limited, when more enum states are seen then these all end up in an overflow row.

JSON files "read backwards" because the left hand side MUST be a string.

 {"one": 1, "two": 2, "four": 4}

Python files use the natural order of key on the left hand side, and replacement text on the right. The "enumtext" identifier name is open coded in the decoder source, and MUST be used.

 enumtext = { 0: "zero", 1: "one", 2: "two", 3: "three", }