Scope API¶
The scope object is used to control the capture/glitch portion of the ChipWhisperer device.
The easiest way to create a scope object is via the chipwhisperer.scope()
function,
which will connect to a ChipWhisperer device and return a scope object of the correct type:
import chipwhisperer as cw
scope = cw.scope()
There are currently two types of scopes:
OpenADC Scope (Lite, Pro, Husky)
ChipWhisperer Nano Scope (Nano)
These scope objects also inherit common methods from Common Scope Attributes
- scope(scope_type=None, name=None, sn=None, idProduct=None, bitstream=None, force=False, prog_speed=10000000, **kwargs) chipwhisperer.scope()¶
Create a scope object and connect to it.
This function allows any type of scope to be created. By default, the object created is based on the attached hardware (OpenADC for CWLite/CW1200, CWNano for CWNano).
- Scope Types:
scopes.OpenADC
(Pro and Lite)scopes.CWNano
(Nano)
If multiple chipwhisperers are connected, the serial number of the one you want to connect to can be specified by passing sn=<SERIAL_NUMBER>
- Parameters
scope_type (
Optional
[Type
[Union
[OpenADC
,CWNano
]]]) – Scope type to connect to. Types can be found in chipwhisperer.scopes. If None, will try to detect the type of ChipWhisperer connected. Defaults to None.name (
Optional
[str
]) –model name of the ChipWhisperer that you want to connect to. Alternative to specifying the serial number when multiple ChipWhisperers, all of different type, are connected. Defaults to None. Valid values:
Lite
Pro
Husky
idProduct (
Optional
[int
]) –idProduct of the ChipWhisperer that you want to connect to. Alternative to specifying the serial number when multiple ChipWhisperers, all of different type, are connected. Defaults to None. Valid values:
0xace2: CW-Lite
0xace3: CW-Pro
0xace5: CW-Husky
sn (
Optional
[str
]) – Serial number of ChipWhisperer that you want to connect to. sn is required if more than one ChipWhisperer of the same type is connected (i.e. two CWNano’s or a CWLite and CWPro). Defaults to None.bitstream (
Optional
[str
]) – Path to bitstream to program. If None, programs default bitstream. Optional, defaults to None. Ignored on Nano.force (
bool
) – If True, always erase and program FPGA. If False, only erase and program FPGA if it is currently blank. Defaults to False. Ignored on Nano.prog_speed (
int
) – Sets the FPGA programming speed for Lite, Pro, and Husky. If you get programming errors, try turning this down.
- Return type
- Returns
Connected scope object.
- Raises
OSError – Can be raised for issues connecting to the chipwhisperer, such as not having permission to access the USB device or no ChipWhisperer being connected.
Warning – Raised if multiple chipwhisperers are connected, but the type and/or the serial numbers are not specified
Changed in version 5.1: Added autodetection of scope_type
Changed in version 5.5: Added idProduct, name, bitstream, and force parameters.
OpenADC Scope¶
Supported scopes:
Usage examples:
- class OpenADC¶
OpenADC scope object.
This class contains the public API for the OpenADC hardware, including the ChipWhisperer Lite/ CW1200 Pro boards. It includes specific settings for each of these devices.
To connect to one of these devices, the easiest method is:
import chipwhisperer as cw scope = cw.scope(scope_type=cw.scopes.OpenADC)
Some sane default settings are available via:
scope.default_setup()
This code will automatically detect an attached ChipWhisperer device and connect to it.
For more help about scope settings, try help() on each of the ChipWhisperer scope submodules (scope.gain, scope.adc, scope.clock, scope.io, scope.trigger, and scope.glitch):
If you have a CW1200 ChipWhisperer Pro/Husky, you have access to some additional features:
Inherits from
chipwhisperer.capture.api.cwcommon.ChipWhispererCommonInterface
- arm()¶
Setup scope to begin capture/glitching when triggered.
The scope must be armed before capture or glitching (when set to ‘ext_single’) can begin.
- Raises
OSError – Scope isn’t connected.
Exception – Error when arming. This method catches these and disconnects before reraising them.
- capture(poll_done=False)¶
Captures trace. Scope must be armed before capturing.
Blocks until scope triggered (or times out), then disarms scope and copies data back.
Read captured data out with
scope.get_last_trace()
- Parameters
poll_done (
bool
) – Supported by Husky only. Poll Husky to find out when it’s done capturing, instead of calculating the capture time based on the capture parameters. Can result in slightly faster captures when the number of samples is high. Defaults to False.- Return type
bool
- Returns
True if capture timed out, false if it didn’t.
- Raises
IOError – Unknown failure.
Changed in version 5.6.1: Added poll_done parameter for Husky
- capture_segmented()¶
Captures trace in segment mode, returns as many segments as buffer holds.
Timeouts not handled yet properly (function will lock). Be sure you are generating enough triggers for segmented mode.
- Returns
True if capture timed out, false if it didn’t.
- Raises
IOError – Unknown failure.
New in version 5.5: Added segmented capture (requires custom bitstream)
- con(sn=None, idProduct=None, bitstream=None, force=False, prog_speed=10000000.0, **kwargs)¶
Connects to attached chipwhisperer hardware (Lite, Pro, or Husky)
- Parameters
sn (str) – The serial number of the attached device. Does not need to be specified unless there are multiple devices attached.
idProduct (int) – The product ID of the ChipWhisperer. If None, autodetects product ID. Optional.
bitstream (str) – Path to bitstream to program. If None, programs default bitstream. Optional.
force (bool) – Force reprogramming of bitstream. If False, only program bitstream if no bitstream is currently programmed. Optional.
- Returns
True if connection is successful, False otherwise
Changed in version 5.5: Added idProduct, bitstream, and force parameters.
- default_setup()¶
Sets up sane capture defaults for this scope
25dB gain
5000 capture samples
0 sample offset
rising edge trigger
7.37MHz clock output on hs2
4*7.37MHz ADC clock
tio1 = serial rx
tio2 = serial tx
CDC settings change off
New in version 5.1: Added default setup for OpenADC
- dis()¶
Disconnects the current scope object.
- Returns
True if the disconnection was successful, False otherwise.
- property fpga_buildtime¶
When the FPGA bitfile was generated. Husky only.
- get_last_trace(as_int=False)¶
Return the last trace captured with this scope.
Can return traces as floating point values (
as_int=False
) or as integers.Floating point values are scaled and shifted to be between -0.5 and 0.5.
Integer values are raw readings from the ChipWhisperer ADC. The ChipWhisperer-Lite has a 10-bit ADC, the Nano has an 8-bit ADC, and the Husky can read either 8-bits or 12-bits of ADC data.
- Parameters
as_int (
bool
) – If False, return trace as a float. Otherwise, return as an int.- Return type
ndarray
- Returns
Numpy array of the last capture trace.
Changed in version 5.6.1: Added as_int parameter
- get_last_trace_segmented()¶
Return last trace assuming it was captued with segmented mode.
NOTE: The length of each returned trace is 1 less sample than requested.
- Returns
2-D numpy array of the last captured traces.
New in version 5.5: Added segmented capture (requires custom bitstream)
- get_name()¶
Gets the name of the attached scope
- Returns
‘ChipWhisperer Lite’ if a Lite, ‘ChipWhisperer Pro’ if a Pro, ‘ChipWhisperer Husky’ if a Husky
- reload_fpga(bitstream=None, reconnect=True, prog_speed=1000000.0)¶
(Re)loads a FPGA bitstream (even if already configured).
Will cause a reconnect event, all settings become default again. If no bitstream specified default is used based on current configuration settings.
- reset_fpga()¶
Reset Husky FPGA. This causes all FPGA-based settings to return to their default values.
scope.gain¶
Class to control ADC gain
- class GainSettings(oaiface, adc)¶
- property db: float¶
The gain of the ChipWhisperer’s low-noise amplifier in dB. Ranges from -6.5 dB to 56 dB, depending on the amplifier settings.
- Getter
Return the current gain in dB (float)
- Setter
Set the gain level in dB
- Raises
ValueError – if new gain is outside of [-6.5, 56]
Examples:
# reading and storing gain_db = scope.gain.db # setting scope.gain.db = 20
- Return type
float
- property gain: int¶
The current LNA gain setting.
This gain is a dimensionless number in the range [0, 78]. Higher value causes higher gain in dB.
Note that this function is unnecessary - the dB gain can be set directly. This property is only here to help convert old scripts.
- Getter
Return the current gain setting (int)
- Setter
Set the gain
- Raises
ValueError – if gain outside [0, 78]
- Return type
int
- property mode: str¶
The current mode of the LNA.
The LNA can operate in two modes: low-gain or high-gain. Generally, the high-gain setting is better to use. Note that this value will be automatically updated if the dB gain is set.
- Getter
Return the current gain mode (“low” or “high”)
- Setter
Set the gain mode
- Raises
ValueError – if mode not one of “low” or “high”
- Return type
str
scope.adc¶
Class to control non-gain, non-clock ADC settings
- class TriggerSettings(oaiface)¶
- property basic_mode¶
The type of event to use as a trigger.
Only applies to the ADC capture - the glitch module is always a rising edge trigger.
- There are four possible types of trigger events:
“low”: triggers when line is low (logic 0)
“high”: triggers when line is high (logic 1)
“rising_edge”: triggers when line transitions from low to high
“falling_edge:” triggers when line transitions from high to low
Warning
This must be set to “rising_edge” if a trigger other than “basic” is used. The SAD/DecodeIO triggers will not work with any other setting!
- Getter
Return the current trigger mode (one of the 4 above strings)
- Setter
Set the trigger mode
- Raises
ValueError – if value is not one of the allowed strings
- clear_clip_errors()¶
ADC clipping errors are sticky until manually cleared by calling this.
- property clip_errors_disabled¶
By default, ADC clipping is flagged as an error. Disable if you do not want this error notification.
- property decimate¶
The ADC downsampling factor.
This value instructs the ChipWhisperer to only record 1 sample in every <decimate>. In other words, if this value is set to 10, the sampling rate is set to 1/10th of the sampling clock.
This setting is helpful for recording very long operations or for reducing the sampling rate for streaming mode.
- Getter
Return an integer with the current decimation factor
- Setter
Set the decimation factor
- Raises
ValueError – if the new factor is not positive
- property fifo_fill_mode¶
The ADC buffer fill strategy - allows segmented usage for CW-lite and CW-pro.
Warning
THIS REQUIRES NEW FPGA BITSTREAM - NOT YET IN THE PYTHON.
Only the ‘Normal’ mode is well supported, the other modes can be used carefully.
For segmenting on CW-Husky, see ‘segments’ instead.
- There are four possible modes:
“normal”: Trigger line & logic work as expected.
- “enable”: Capture starts with rising edge, but writing samples
is enabled by active-high state of trigger line.
- “segment”: Capture starts with rising edge, and writes trigger.samples
to buffer on each rising edge, stopping when the buffer is full. For this to work adc.samples must be a multiple of 3 (will be enforced by API).
Warning
The “enable” and “segment” modes requires you to fill the full buffer (~25K on CW-Lite, ~100K on CW-Pro). This requires you to ensure the physical trigger line will be high (enable mode) or toggle (segment mode) enough. The ChipWhisperer hardware will currently stall until the internal buffer is full, and future commands will fail.
Warning
adc.basic_mode must be set to “rising_edge” if a fill_mode other than “normal” is used. Bad things happen if not.
- Getter
Return the current fifo fill mode (one of the 3 above strings)
- Setter
Set the fifo fill mode
- Raises
ValueError – if value is not one of the allowed strings
- property fifo_state¶
return the state of the Husky FIFO FSM.
- Type
Husky only, for debugging
- property lo_gain_errors_disabled¶
By default, captures which use less than a quarter of the ADC’s dynamic range flag an error, to indicate that the gain should be increased. Disable if you do not want this error notification.
- property offset¶
The number of samples to wait before recording data after seeing a trigger event.
This offset is useful for long operations. For instance, if an encryption is 1 million samples long, it’s difficult to capture the entire power trace, but an offset can be used to skip to the end of the encryption.
The offset must be a 32 bit unsigned integer.
- Getter
Return the current offset (integer)
- Setter
Set a new offset
- Raises
ValueError – if offset outside of range [0, 2**32)
- property presamples¶
The number of samples to record from before the trigger event.
This setting must be a positive integer, and it cannot be larger than the number of samples. When streaming mode is enabled, this value is set to 0.
- Getter
Return the current number of presamples
- Setter
Set the number of presamples.
- Raises
ValueError – if presamples is outside of range [0, samples]
- property samples¶
The number of ADC samples to record in a single capture.
The maximum number of samples is hardware-dependent: - cwlite: 24400 - cw1200: 96000 - cwhusky: 131070
- Getter
Return the current number of total samples (integer)
- Setter
Set the number of samples to capture
- Raises
ValueError – if number of samples is negative
- property state¶
The current state of the trigger input.
This is a digital value (ie: high or low), which is some combination of the pins in the triggermux object. Read-only.
Getter: Return the current state (True or False).
- property timeout¶
The number of seconds to wait before aborting a capture.
If no trigger event is detected before this time limit is up, the capture fails and no data is returned.
- Getter
Return the number of seconds before a timeout (float)
- Setter
Set the timeout in seconds
- property trig_count¶
The number of samples that the trigger input was active.
This value indicates how long the trigger was high or low last time a trace was captured. It is the number of samples where the input was low (in “low” or “falling edge” modes) or high (in “high” or “rising edge” modes). Read-only.
This counter is not meaningful if the trigger is still active.
- Getter
Return the last trigger duration (integer)
scope.adc Pro/Husky Only¶
The following scope.adc
members are only available on ChipWhisperer-Husky, ChipWhisperer-Pro, or both.
- class TriggerSettings(oaiface)
- property TriggerSettings.stream_mode¶
The ChipWhisperer’s streaming status. Only available on CW1200 and CW-Husky.
When stream mode is enabled, the ChipWhisperer sends back ADC data as soon as it is recorded. In this mode, there is no hardware limit on the maximum number of samples per trace (although Python may run out of memory when recording billions of points). However, there is a maximum streaming data rate, which is approximately 10 Msamp/s.
Note that no pre-trigger samples can be recorded when stream mode is enabled.
- Getter
Return True if stream mode is enabled and False otherwise
- Setter
Enable or disable stream mode
- property TriggerSettings.segment_cycles¶
Number of clock cycles separating segments.
Warning
Supported by CW-Husky only. For segmenting on CW-lite or CW-pro, see ‘fifo_fill_mode’ instead.
This setting must be a 20-bit positive integer.
When ‘segments’ is greater than one, set segment_cycles to a non-zero value to capture a new segment every ‘segment_cycles’ clock cycles following the initial trigger event. ‘segment_cycle_counter_en’ must also be set.
Typically, segment_cycles should be much greater than scope.adc.samples. If they are too close, capture will fail (indicated by the blinking red lights and scope.adc.errors showing either a segmenting error or a FIFO over/underflow error). When presamples = 0, segment_cycles >= samples + 10. When presamples > 0, segment_cycles >= samples + presamples AND segment_cycles >= samples + 10.
- Getter
Return the current value of segment_cycles.
- Setter
Set segment_cycles.
- Raises
ValueError – if segments is outside of range [0, 2^20-1]
- property TriggerSettings.segment_cycle_counter_en¶
Number of clock cycles separating segments.
Warning
Supported by CW-Husky only. For segmenting on CW-lite or CW-pro, see ‘fifo_fill_mode’ instead.
Set to 0 to capture a new power trace segment every time the target issues a trigger event.
Set to 1 to capture a new power trace segment every ‘segment_cycles’ clock cycles after a single trigger event.
- Getter
Return the current value of segment_cycle_counter_en.
- Setter
Set segment_cycles.
- property TriggerSettings.first_error_state¶
Reports the state the FPGA FSM state at the time of the first flagged error. Useful for debugging. Read-only.
Warning
Supported by CW-Husky only.
- Getter
Return the error flags.
- property TriggerSettings.errors¶
Internal error flags (FPGA FIFO over/underflow)
Warning
Supported by CW-Husky only.
- Error types and their causes:
- ‘presample error’: capture trigger occurs before the requested
number of presamples have been collected. Reduce scope.adc.presamples or delay the capture trigger.
- ‘ADC clipped’: gain is too high; reduce it (scope.gain) or disable
this error (scope.adc.clip_errors_disabled).
- ‘gain too low error’: gain is “too low” (4 bits or more of the ADC’s
dynamic range did not get used); increase it (scope.gain) or disable this error (scope.adc.lo_gain_errors_disabled).
- ‘invalid downsample setting’: using downsampling (aka decimating) with
presamples and multiple segments is not allowed.
- ‘segmenting error’: the condition for starting the capture of the next
segment came true before the capture of the current segment completed. Reduce the segment size and/or increase the time between segments.
- ‘fast FIFO underflow’: shouldn’t occur in isolation without
other errors being flagged.
- ‘fast FIFO overflow’: data is coming in fast than it’s being read;
reduce scope.clock.adc_freq.
- ‘slow FIFO underflow’: host tried to read more ADC samples than are
available.
- ‘slow FIFO overflow’: data is coming in faster than it’s being
read; reduce scope.clock.adc_freq.
To fully understand the four different FIFO errors (fast/slow over/underflows), some background on Husky’s sample storage architecture is required. ADC samples are first stored in a “fast” FIFO which runs at the ADC sampling rate, then moved to a wider and “slower” FIFO which is read by the host. Overflows or underflows can occur in either FIFO. Errors can be caused from an illegal configuration of scope.adc (e.g. too many samples), or attempting to stream too fast.
- Getter
Return the error flags.
- Setter
Clear error flags.
- property TriggerSettings.segments¶
Number of sample segments to capture.
Warning
Supported by CW-Husky only. For segmenting on CW-lite or CW-pro, see ‘fifo_fill_mode’ instead.
This setting must be a 16-bit positive integer.
In normal operation, segments=1.
Multiple segments are useful in two scenarios:
- Capturing only subsections of a power trace, to allow longer
effective captures. After a trigger event, the requested number of samples is captured every ‘segment_cycles’ clock cycles, ‘segments’ times. Set ‘segment_cycle_counter_en’ to 1 for this segment mode.
- Speeding up capture times by capturing ‘segments’ power traces from
a single arm + capture event. Here, the requested number of samples is captured at every trigger event, without having to re-arm and download trace data between every trigger event. Set ‘segment_cycle_counter_en’ to 0 for this segment mode.
Warning
when capturing multiple segments with presamples, the total number of samples per segment must be a multiple of 3. Incorrect sample data will be obtained if this is not the case.
- Getter
Return the current number of presamples
- Setter
Set the number of presamples.
- Raises
ValueError – if segments is outside of range [1, 2^16-1]
- property TriggerSettings.bits_per_sample¶
Bits per ADC sample. Only available on CW-Husky.
Husky has a 12-bit ADC; optionally, we read back only 8 bits per sample. This does not allow for more samples to be collected; it only allows for a faster sampling rate in streaming mode.
- Getter
return the number of bits per sample that will be received.
- Setter
set the number of bits per sample to receive.
scope.clock¶
scope.clock (Lite/Pro Only)¶
Warning
ChipWhisperer-Lite/Pro only. See
scope.clock (Husky)
for Husky clock documentation.
Class to control target/ADC clocks. A block diagram of the clock module is shown below:
![]()
- class ClockSettings(oaiface, hwinfo=None)¶
- property adc_freq¶
The current frequency of the ADC clock in Hz. Read-only.
This clock frequency is derived from one of the ADC clock sources as described in adc_src.
- Getter
Return the current frequency in MHz (float). May take up to 0.5s to stabilize after adc_locked is True.
- property adc_locked¶
The current status of the ADC DCM. Read-only.
To try re-locking the ADC, see reset_adc().
- Getter
Return whether the ADC DCM is locked (True or False)
- property adc_phase¶
Fine adjustment for the ADC sampling point.
This setting moves the sampling point approximately 5 ns forward or backward, regardless of the sampling frequency. It may be helpful to improve the stability of the measurement.
The value of this setting is dimensionless and has a non-linear effect on the phase adjustment.
- Getter
Return the current phase setting (integer) NOTE: This getter is currently broken due to an FPGA bug.
- Setter
Set a new phase offset
- Raises
ValueError – if offset not in [-32767, 32767] (Husky) or [-255, 255] (others)
TypeError – if offset not integer
- property adc_rate¶
The current sampling rate of the ADC clock in samples/s. Read-only.
Note that the sampling rate may be less than the clock frequency if the downsampling factor is greater than 1.
- Getter
Return the current sampling rate in MS/s (float)
- property adc_src¶
The clock source for the ADC module.
The ADC can be clocked by one of five possible sources:
“clkgen_x1”: CLKGEN output via DCM
“clkgen_x4”: CLKGEN output via DCM with x4 clk multiplier
“extclk_x1”: External clock input via DCM
“extclk_x4”: External clock input via DCM with x4 clk multiplier
“extclk_dir”: External clock input with no DCM
- Getter
Return the current ADC clock source (one of five strings above)
- Setter
Set the ADC clock source and reset the ADC DCM to lock it.
- Raises
ValueError – if string not in valid settings
- property clkgen_div¶
The divider in the CLKGEN DCM.
This divider must be in the range [1, 256].
- Getter
Return the current CLKGEN divider (integer)
- Setter
Set a new CLKGEN divider.
- property clkgen_freq¶
The CLKGEN output frequency in Hz.
The CLKGEN module takes the input source and multiplies/divides it to get a faster or slower clock as desired. Minimum clock in practice is 3.2MHz.
- Getter
Return the current calculated CLKGEN output frequency in Hz (float). Note that this is the theoretical frequency - use the freq counter to determine the actual output. May take up to 0.5s to stabilize after clkgen_locked is True.
- Setter
Attempt to set a new CLKGEN frequency in Hz. When this value is set, all possible DCM multiply/divide settings are tested to find which is closest to the desired output speed. If EXTCLK is the CLKGEN source, the EXTCLK frequency must be properly set for this to work. Also, both DCMs are reset.
- property clkgen_locked¶
The current status of the CLKGEN DCM. Read-only.
- Getter
Return whether the CLKGEN DCM is locked (True or False)
- property clkgen_mul¶
The multiplier in the CLKGEN DCM.
This multiplier must be in the range [2, 256].
- Getter
Return the current CLKGEN multiplier (integer)
- Setter
Set a new CLKGEN multiplier.
- property clkgen_src¶
The input source for the CLKGEN DCM.
This DCM can receive input from one of two places:
“extclk”: The external clock input
“system” or “internal”: The system clock (96 MHz)
- Getter
Return the current CLKGEN input (either “extclk” or “system”)
- Setter
Change the CLKGEN source and reset all the DCMs.
- Raises
ValueError – if source is not one of three strings above
- property enabled¶
Controls whether the Xilinx MMCM used to generate the target clock is powered on or not. In Husky, an external PLL is used instead; this FPGA PLL is still present but disabled by default because MMCMs are quite power-hungry.
- property extclk_freq¶
The input frequency from the EXTCLK source in Hz.
This value is used to help calculate the correct CLKGEN settings to obtain a desired output frequency when using EXTCLK as CLKGEN input. It is not a frequency counter - it is only helpful if the EXTCLK frequency is already known.
- Getter
Return the last set EXTCLK frequency in MHz (int)
- Setter
Update the EXTCLK frequency
- property freq_ctr¶
The current frequency at the frequency counter in MHz. Read-only.
The frequency counter can be used to check the speed of the CLKGEN output or the EXTCLK input. This value shows the current frequency reading.
- Getter
Return the current frequency in MHz (float)
- property freq_ctr_src¶
The current input to the frequency counter.
There are two possible inputs to the frequency counter: - “clkgen”: The CLKGEN DCM output - “extclk”: The external input clock signal
- Getter
Return the frequency counter input (one of the above strings)
- Setter
Set the frequency counter source
- Raises
ValueError – if source is not “clkgen” or “extclk”
- reset_adc()¶
Reset the ADC DCM.
After changing frequencies, the ADC DCM may become unlocked from its input signal. This function resets the DCM to re-lock it.
If the DCM is still unlocked after calling this function, the clock may be too fast for the ADC.
- reset_clkgen()¶
Reset the CLKGEN DCM.
After changing frequencies or input sources, the CLKGEN DCM may not be locked. This function resets the DCM to re-lock it.
If the DCM is still unlocked after calling this function, the clock may be too fast for the CLKGEN module.
- reset_dcms()¶
Reset the CLKGEN DCM, then the ADC DCM.
This order is necessary because the ADC may depend on having a locked clock from the CLKGEN output.
scope.clock (Husky Only)¶
- class ChipWhispererHuskyClock(oaiface, fpga_clk_settings, mmcm1, mmcm2)¶
- property adc_freq¶
Calculates the ADC frequency based on clkgen_freq and adc_mul
Read-only
- property adc_locked¶
Convenience function for backwards compatibility with how ADC clocks are managed on CW-lite and CW-pro.
- property adc_mul¶
Sets a new ADC clock frequency by multiplying this value by clkgen_freq
Must be a positive integer, or 0. If 0, turns the ADC clock off.
adc_freq = adc_mul * clkgen_freq
Note that the value of adc_mul affects how closely clkgen_freq can be matched to the requested frequency. See clkgen_freq for more information.
- Getter
The currently set adc multiplier
- Setter
Set the adc multiplier
- property adc_phase¶
Changes the phase of the ADC clock relative to the target clock
Positive values delay the ADC clock compared to the target clock and vice versa.
Note: The actual phase is only a 6 bit signed value compared to a 9 bit signed value on the Lite/Pro. This is mapped onto the same [-255, 255] range, meaning not all phases between -255 and 255 are possible.
- Getter
Gets the current adc_phase
- Setter
Sets the adc_phase. Must be in the range [-255, 255]
- property adc_src¶
Convenience function for backwards compatibility with how ADC clocks are set on CW-lite and CW-pro.
The ADC can be clocked by one of five possible sources:
“clkgen_x1”: CLKGEN output via DCM
“clkgen_x4”: CLKGEN output via DCM with x4 clk multiplier
“extclk_x1”: External clock input via DCM
“extclk_x4”: External clock input via DCM with x4 clk multiplier
“extclk_dir”: External clock input with no DCM
- Getter
Return the current ADC clock source (one of five strings above)
- Setter
Set the ADC clock source and reset the ADC DCM to lock it.
- Raises
ValueError – if string not in valid settings
- property clkgen_freq¶
The target clock frequency in Hz.
The PLL takes the input clock frequency and multiplies it/divides to match as closely as possible to the set clkgen_freq. If set to 0, turns both the target and ADC clocks off.
Some important notes for setting this value:
The minimum output frequency is 500kHz and the maximum is 350MHz
- The ADC clock output frequency (clkgen_freq * adc_mul) must be
below 200MHz. Therefore, if you want to use a clkgen_freq above 200MHz, you must set adc_mul=0
- The accuracy of the actual clkgen_freq will depend
on adc_mul, as the output divisor for the clkgen_freq must divide cleanly by adc_mul. For example, if you try to use a clkgen_freq of 7.37MHz and and adc_mul of 16, the closest valid clkgen_freq will be 7.5MHz.
- Getter
Return the calculated target clock frequency in Hz
- Setter
Attempt to set a new target clock frequency in Hz
- property clkgen_locked¶
Checks if the Husky PLL is locked
- property clkgen_src¶
The input for the Husky’s PLL, which generates clocks for the target and the ADC.
The PLL can receive input from two places:
“system” or “internal”: An onboard crystal
“extclk”: An external clock (e.g. generated by the target).
When clkgen_src is set to “extclk”, the external clock frequency is measured to set the ADC clock accordingly. If the external clock frequency is later modified, then clkgen_src must be re-set to “extclk” in order for the frequency change to be recognized. Otherwise, the ADC sampling clock will remain tied to the previous external clock frequency.
A variant on “extclk” is “extclk_aux_io”, when the external clock is supplied on the AUX I/O MCX instead of the HS1 pin (scope.io.aux_io_mcx must be set to “high_z” in this case).
- Getter
Return the current PLL input (“system”, “extclk” or “extclk_aux_io”)
- Setter
Change the CLKGEN source
- Raises
ValueError – if source is not one of the above
- property extclk_error¶
When the external clock is used, a change in clock frequency exceeding extclk_error will flag an error. The purpose of this is to remind you that you need to set scope.clock.clkgen_freq to the frequency of your external clock.
- Getter
Whether the external clock monitor has flagged an error.
- Setter
Clear the error.
- property extclk_monitor_enabled¶
When enabled, any change in the external clock frequency input exceeding the amount set in self.extclk_tolerance will trigger an error.
When using an external clock to drive ChipWhisperer (i.e. self.clkgen_src == ‘extclk’), Husky must know the frequency of that clock (by setting scope.clock.clkgen_freq). This clock monitor is a convenience to flag when the frequency changes without Husky being informed of that change.
- Getter
Whether the external clock monitor is enabled.
- Setter
Enable/disable the external clock monitor.
- property extclk_tolerance¶
Tolerance for external clock frequency change, measured in Hz. If the difference between consecutive measurements exceeds this, an error is flagged. Defaults to ~100 Hz.
- Getter
Get the frequency change tolerance [Hz].
- Setter
Set the frequency change tolerance [Hz].
- property fpga_vco_freq¶
Set the FPGA clock glitch PLL’s VCO frequency.
Affects
scope.glitch.phase_shift_steps
Allowed range: 600 - 1200 MHz.
- Getter
Calculate vco from last set value [Hz]
- Setter
Set the vco frequency [Hz]
- Raises
ValueError – set vco out of valid range
- property freq_ctr¶
Reads the frequency of the external input clock
- reset_adc()¶
Convenience function for backwards compatibility with how ADC clocks are managed on CW-lite and CW-pro.
- reset_dcms()¶
Reset the lock on the Husky’s PLL.
scope.io¶
Module to control IO pins
- class GPIOSettings(cwextra)¶
- property aux_io_mcx¶
Set the function of the AUX I/O MCX on Husky. Options: * “high_z”: input: to use as a trigger (scope.trigger.triggers = ‘mcx’) or clock (scope.clock.clk_src = ‘extclk_aux_io’). * “hs2”: output: provide the same clock that’s on HS2.
- property cdc_settings¶
Check or set whether USART settings can be changed via the USB CDC connection
i.e. whether you can change USART settings (baud rate, 8n1) via a serial client like PuTTY
- Getter
An array of length four for four possible CDC serial ports (though only one is used)
- Setter
Can set either via an integer (which sets both ports) or an array of length 4 (which sets each port)
Returns None if using firmware before the CDC port was added
- property extclk_src¶
The clock signal being used as input for EXTCLK.
Currently, this can only be HS1, which is the clock from the target. As such, this value is read-only.
- property glitch_hp¶
Whether the high-power crowbar MOSFET is enabled.
The glitch output is an SMA-connected output line that is normally connected to a target’s power rails. If this setting is enabled, a high-powered MOSFET shorts the power-rail to ground when the glitch module’s output is active.
Warning
Use with caution - ensure that the glitch module is properly configured before enabling this setting, as it is possible to permanently damage hardware with this output.
- Getter
Return True if enabled or False if disabled
- Setter
Turn the high-power MOSFET on or off
- property glitch_lp¶
Whether the low-power crowbar MOSFET is enabled.
This is the low-power version of glitch_hp - see that documentation for more details.
Warning
Use with caution - ensure that the glitch module is properly configured before enabling this setting, as it is possible to permanently damage hardware with this output.
- property glitch_trig_mcx¶
Set the function of the Trigger/Glitch Out MCX on Husky. Options: * “glitch”: glitch output (clock or voltage glitch signal, as defined by scope.glitch settings) * “trigger”: internal trigger signal (as defined by scope.trigger)
- property hs2¶
The clock signal routed to the HS2 high speed output pin.
- Allowed clock signals are:
“clkgen”: The output from the CLKGEN module
“glitch”: The output from the glitch module
“disabled” / None: No clock; output driven low
- Getter
Return one of “clkgen”, “glitch”, or “disabled”
- Setter
Set the clock to be output on HS2.
Raises: ValueError: if new value not listed above
- property nrst¶
The state of the NRST pin.
See pdic for more information.
- property pdic¶
The function of the PDIC pin output pin.
- This is a GPIO pin. The following values are allowed:
“high” / True: logic 1
“low” / False: logic 0
“disabled” / “default” / “high_z” / None: undriven
- Getter
Return one of “high”, “low”, or “high_z”. This shows how ChipWhisperer is driving this pin; it does not show its actual logic level.
- Setter
Set the pin’s state
Raises: ValueError: if new state not listed above
- property pdid¶
The state of the PDID pin.
See pdic for more information.
- property target_pwr¶
Whether the target board is powered by the ChipWhisperer.
If True, the ChipWhisperer is currently supplying power to the target board; if False, it is not. This setting can be used to cycle power to the target or to help program it.
If the target board is powered through an external supply, this setting may have no effect.
- Getter
Return the current power state of the target (True or False)
- Setter
Turn the target power on or off.
- property tio1¶
The function of the Target IO1 pin.
- TIO1 can be used for the following functions:
“serial_rx”: UART input
“serial_tx”: UART output
“high_z” / None: High impedance input
“gpio_low” / False: Driven output: logic 0
“gpio_high” / True: Driven output: logic 1
“gpio_disabled”: Driven output: no effect
Default value is “serial_rx”.
- Getter
Return one of the above strings. This shows how ChipWhisperer is driving this pin; it does not show its actual logic level. Use scope.io.tio_states to see the actual logic level.
- Setter
Set the Target IO1 mode.
- Raises
ValueError – if new value is not one of the above modes
- property tio2¶
The function of the Target IO2 pin.
- TIO2 can be used for the following functions:
“serial_rx”: UART input
“serial_tx”: UART output
“high_z” / None: High impedance input
“gpio_low” / False: Driven output: logic 0
“gpio_high” / True: Driven output: logic 1
“gpio_disabled”: Driven output: no effect
Default value is “serial_tx”.
- Getter
Return one of the above strings. This shows how ChipWhisperer is driving this pin; it does not show its actual logic level. Use scope.io.tio_states to see the actual logic level.
- Setter
Set the Target IO2 mode.
- Raises
ValueError – if new value is not one of the above modes
- property tio3¶
The function of the Target IO3 pin.
- TIO3 can be used for the following functions:
“serial_rx”: UART input
“serial_tx”: UART output
“serial_tx_rx”: UART 1-wire I/O (for smartcards)
“high_z” / None: High impedance input
“gpio_low” / False: Driven output: logic 0
“gpio_high” / True: Driven output: logic 1
“gpio_disabled”: Driven output: no effect
Default value is “high_z”.
- Getter
Return one of the above strings. This shows how ChipWhisperer is driving this pin; it does not show its actual logic level. Use scope.io.tio_states to see the actual logic level.
- Setter
Set the Target IO3 mode.
- Raises
ValueError – if new value is not one of the above modes
- property tio4¶
The function of the Target IO4 pin.
- TIO4 can be used for the following functions:
“serial_tx”: UART output
“high_z” / None: High impedance input
“gpio_low” / False: Driven output: logic 0
“gpio_high” / True: Driven output: logic 1
“gpio_disabled”: Driven output: no effect
Default value is “high_z”. Typically, this pin is used as a trigger input.
- Getter
Return one of the above strings. This shows how ChipWhisperer is driving this pin; it does not show its actual logic level. Use scope.io.tio_states to see the actual logic level.
- Setter
Set the Target IO4 mode
- Raises
ValueError – if new value is not one of the above modes
- property tio_states¶
Reads the logic level of the TIO pins (1-4) and returns them as a tuple of the logic levels.
Warning
ChipWhisperer firmware before release 5.2.1 does not support reading the TIO pins!
- Getter
Read TIO states
- Returns
A tuple of 1’s and 0’s representing the logic levels of each TIO pin
New in version 5.3: Add documented interface for the old method of reading TIO pins
scope.trigger¶
Basic trigger control module
- class TriggerSettings(cwextra)¶
- property module¶
The trigger module in use.
The trigger modules available depend on the hardware. On the CWLite, only the basic trigger module can be used; on the CW1200, the serial data and SAD triggers are available too.
- Available trigger modules:
‘basic’: Trigger on a logic level or edge
- Getter
Returns ‘basic’
- property triggers¶
The logical input into the trigger module.
The trigger module uses some combination of the scope’s I/O pins to produce a single value, which it uses for edge/level detection or UART triggers. This trigger output can combine 5 pins using one of 3 different boolean operations. N/A for ‘trace’ trigger module (see scope.trace.trace_mode for how to connect trace pins.)
- Pins:
tio1-4: Target I/O pins 1-4. Note that these pins can be in any mode.
nRST: Target I/O pin nRST. Note that these pins can be in any mode.
sma: An auxiliary SMA input, if available (only on CW1200)
- Boolean operations:
OR: True if any inputs are True; False if none are
AND: True if all inputs are True; False if any are not
NAND: False if all inputs are True; True if any are not
Note that only one boolean operation can be used over all input pins.
- Examples of acceptable trigger inputs:
“tio1”
“tio3 OR tio4”
“tio1 NAND tio2 NAND sma”
“nrst”
- Examples of unallowed trigger inputs:
“tio1 tio2”
“tio1 AND tio2 OR tio3”
“tio1 OR tio1”
“tio1 XOR tio2”
“serial-tx”
- Getter
Return a string describing the trigger mode (see examples)
- Setter
Set the trigger mode using a string like the ones above
- Raises
ValueError – if string cannot be converted to a legal mode
scope.trigger (Pro/Husky Only)¶
- class ProTrigger(cwextra)¶
- property aux_out¶
Controls AUX out on the CWPro
CWPro only
- Getter
Returns True if yes, False if no
- Setter
Set True to enable aux_out, False to disable
- property module¶
The trigger module in use.
The trigger modules available depend on the hardware. On the CWLite, only the basic trigger module can be used; on the CW1200, the serial data and SAD triggers are available too.
- Available trigger modules:
‘basic’: Trigger on a logic level or edge
‘SAD’: Trigger from SAD module (CWPro only)
‘DECODEIO’: Trigger from decode_IO module (CWPro only)
- Getter
Return the active trigger module
- Setter
Sets the active trigger module
- Raises
ValueError – module isn’t one of the available strings
scope.glitch¶
Module to control glitching. A block diagram of the module is shown below:
- class GlitchSettings(cwglitch)¶
- property actual_num_glitches¶
The number of glitches that were generated during the previous glitch event (should equal scope.glitch.num_glitches; for debugging). CW-Husky only.
- property arm_timing¶
When to arm the glitch in single-shot mode.
If the glitch module is in “ext_single” trigger mode, it must be armed when the scope is armed. There are two timings for this event:
“no_glitch”: The glitch module is not armed. Gives a moderate speedup to capture.
“before_scope”: The glitch module is armed first.
“after_scope”: The scope is armed first. This is the default.
This setting may be helpful if trigger events are happening very early.
If the glitch module is not in external trigger single-shot mode, this setting has no effect.
- Getter
Return the current arm timing (“before_scope” or “after_scope”)
- Setter
Change the arm timing
- Raises
ValueError – if value not listed above
- property clk_src¶
The clock signal that the glitch DCM is using as input.
- This DCM can be clocked from three different sources:
“target”: The HS1 clock from the target device (can also be AUX clock for Husky)
“clkgen”: The CLKGEN DCM output (N/A for Husky)
“pll”: Husky’s on-board PLL clock (Husky only)
- Getter
Return the clock signal currently in use
- Setter
Change the glitch clock source
- Raises
ValueError – New value not one of “target”, “clkgen” or “pll”
- property ext_offset¶
How long the glitch module waits between a trigger and a glitch.
After the glitch module is triggered, it waits for a number of clock cycles before generating glitch pulses. This delay allows the glitch to be inserted at a precise moment during the target’s execution to glitch specific instructions.
For CW-Husky when scope.glitch.num_glitches > 1, this parameter is a list with scope.glitch.num_glitches elements, each element representing the ext_offset value for the corresponding glitch.
For CW-Lite/Pro, scope.glitch.num_glitches is not supported so this is a simply an integer.
Has no effect when trigger_src = ‘manual’ or ‘continuous’.
Note
It is possible to get more precise offsets by clocking the glitch module faster than the target board.
This offset must be in the range [0, 2**32).
- Getter
Return the current external trigger offset(s). For CW-lite/pro or when num_glitches=1, this is an integer (for backwards compatibility). Otherwise, it is a list of integers.
- Setter
Set the external trigger offset(s). Integer for CW-lite/pro, list of integers for Husky.
- Raises
TypeError – if offset not an integer, or list of integers for Husky
ValueError – if any offset outside of range [0, 2**32)
- manual_trigger()¶
Manually trigger the glitch output.
This trigger is most useful in Manual trigger mode, where this is the only way to cause a glitch.
- property num_glitches¶
The number of glitch events to generate. CW-Husky only.
Each glitch event uses the same offset and width settings. Glitch event x uses repeat[x] and ext_offset[x].
This parameter has no effect when scope.glitch.trigger_src is set to “manual” or “continuous”.
- Raises
ValueError – number outside of [1, 32].
- property offset¶
The offset from a rising clock edge to a glitch pulse rising edge.
For CW-Husky, offset is expressed as the number of phase shift steps. Minimum offset is obtained at 0 (rising edge of glitch aligned with rising edge of glitch source clock). At scope.glitch.phase_shift_steps/2, the glitch rising edge is aligned with the glitch source clock falling edge. Negative values are allowed, but -x is equivalent to scope.glitch.phase_shift_steps-x. The setting rolls over (+x is equivalent to scope.glitch.phase_shift_steps+x). Run the notebook in jupyter/demos/husky_glitch.ipynb to visualize glitch settings.
For other capture hardware (CW-lite, CW-pro), offset is expressed as a percentage of one period. A pulse may begin anywhere from -49.8% to 49.8% away from a rising edge, allowing glitches to be swept over the entire clock cycle.
Warning
very large negative offset <-45 may result in double glitches (CW-lite/pro only).
- Getter
Return an int (Husky) or float (CW-lite/pro) with the current glitch offset.
- Setter
Set the glitch offset. For CW-lite/pro, the new value is rounded to the nearest possible offset.
- Raises
UserWarning – value outside range [-50, 50] (value is rounded) (CW-lite/pro only)
- property offset_fine¶
The fine adjustment value on the glitch offset. N/A for Husky.
This is a dimensionless number that makes small adjustments to the glitch pulses’ offset. Valid range is [-255, 255].
Warning
This value is write-only. Reads will always return 0.
- Getter
Returns 0
- Setter
Update the glitch fine offset
- Raises
TypeError – if offset not an integer
ValueError – if offset is outside of [-255, 255]
- property output¶
The type of output produced by the glitch module.
There are 5 ways that the glitch module can combine the clock with its glitch pulses:
“clock_only”: Output only the original input clock.
“glitch_only”: Output only the glitch pulses - do not use the clock.
“clock_or”: Output is high if either the clock or glitch are high.
“clock_xor”: Output is high if clock and glitch are different.
“enable_only”: Output is high for glitch.repeat cycles.
- Some of these settings are only useful in certain scenarios:
Clock glitching: “clock_or” or “clock_xor”
Voltage glitching: “glitch_only” or “enable_only”
- Getter
Return the current glitch output mode (one of above strings)
- Setter
Change the glitch output mode.
- Raises
ValueError – if value not in above strings
- readStatus()¶
Read the status of the two glitch DCMs.
- Returns
A tuple with 4 elements:
* phase1: Phase shift of DCM1 (N/A for Husky), * phase2: Phase shift of DCM2 (N/A for Husky), * lock1: Whether DCM1 is locked, * lock2: Whether DCM2 is locked
- property repeat¶
The number of glitch pulses to generate per trigger.
When the glitch module is triggered, it produces a number of pulses that can be combined with the clock signal. This setting allows for the glitch module to produce stronger glitches (especially during voltage glitching).
For CW-Husky when scope.glitch.num_glitches > 1, this parameter is a list with scope.glitch.num_glitches elements, each element representing the repeat value for the corresponding glitch.
For CW-Lite/Pro, scope.glitch.num_glitches is not supported so this is a simply an integer.
Has no effect when trigger_src = ‘continuous’.
Repeat counter must be in the range [1, 8192].
- Getter
Return the current repeat value. For CW-lite/pro or when num_glitches=1, this is an integer (for backwards compatibility). Otherwise, it is a list of integers.
- Setter
Set the repeat counter. Integer for CW-lite/pro, list of integers for Husky.
- Raises
TypeError – if value not an integer, or list of integers for Husky
ValueError – if any value outside [1, 8192]
- resetDCMs(keepPhase=True)¶
Reset the two glitch DCMs.
This is automatically run after changing the glitch width or offset, so this function is typically not necessary.
- property state¶
Glitch FSM state. CW-Husky only. For debug. Writing any value resets the FSM to its idle state.
- property trigger_src¶
The trigger signal for the glitch pulses.
- The glitch module can use four different types of triggers:
- “continuous”: Constantly trigger glitches. The following
scope.glitch parameters have no bearing in this mode: ext_offset, repeat, num_glitches.
- “manual”: Only trigger glitches by calling manual_trigger(). The
following scope.glitch parameters have no bearing in this mode: ext_offset, num_glitches.
- “ext_single”: Use the trigger module. Once the scope is armed, one
set of glitch events is emitted when the trigger condition is satisfied. Subsequent trigger conditions are ignored unless the scope is re-armed.
- “ext_continuous”: Use the trigger module. A set of glitch events is
emitted each time the trigger condition is satisfied, whether or not the scope is armed.
Warning
calling
scope.arm()
in manual gitch mode will cause a glitch to trigger.
- Getter
Return the current trigger source.
- Setter
Change the trigger source.
- Raises
ValueError – value not listed above.
- property width¶
The width of a single glitch pulse.
For CW-Husky, width is expressed as the number of phase shift steps. Minimum width is obtained at 0. Maximum width is obtained at scope.glitch.phase_shift_steps/2. Negative values are allowed, but -x is equivalent to scope.glitch.phase_shift_steps-x. The setting rolls over (+x is equivalent to scope.glitch.phase_shift_steps+x). Run the notebook in jupyter/demos/husky_glitch.ipynb to visualize glitch settings.
For other capture hardware (CW-lite, CW-pro), width is expressed as a percentage of one period. One pulse can range from -49.8% to roughly 49.8% of a period. The system may not be reliable at 0%. Note that negative widths are allowed; these act as if they are positive widths on the other half of the clock cycle.
- Getter
Return an int (Husky) or float (others) with the current glitch width.
- Setter
Update the glitch pulse width. For CW-lite/pro, the value is adjusted to the closest possible glitch width.
- Raises
UserWarning – Width outside of [-49.8, 49.8]. The value is rounded to one of these. (CW-lite/pro only)
- property width_fine¶
The fine adjustment value on the glitch width. N/A for Husky.
This is a dimensionless number that makes small adjustments to the glitch pulses’ width. Valid range is [-255, 255].
Warning
This value is write-only. Reads will always return 0.
- Getter
Returns 0
- Setter
Update the glitch fine width
- Raises
TypeError – offset not an integer
ValueError – offset is outside of [-255, 255]
scope.glitch (Husky Only)¶
The following attributes are only available on, or differ substantially on the ChipWhisperer-Husky
- class GlitchSettings(cwglitch)
- GlitchSettings.enabled¶
Husky only. Whether the Xilinx MMCMs used to generate glitches are powered on or not. 7-series MMCMs are power hungry and are estimated to consume half of the FPGA’s power. If you run into temperature issues and don’t require glitching, you can power down these MMCMs.
- GlitchSettings.width
The width of a single glitch pulse.
For CW-Husky, width is expressed as the number of phase shift steps. Minimum width is obtained at 0. Maximum width is obtained at scope.glitch.phase_shift_steps/2. Negative values are allowed, but -x is equivalent to scope.glitch.phase_shift_steps-x. The setting rolls over (+x is equivalent to scope.glitch.phase_shift_steps+x). Run the notebook in jupyter/demos/husky_glitch.ipynb to visualize glitch settings.
For other capture hardware (CW-lite, CW-pro), width is expressed as a percentage of one period. One pulse can range from -49.8% to roughly 49.8% of a period. The system may not be reliable at 0%. Note that negative widths are allowed; these act as if they are positive widths on the other half of the clock cycle.
- Getter
Return an int (Husky) or float (others) with the current glitch width.
- Setter
Update the glitch pulse width. For CW-lite/pro, the value is adjusted to the closest possible glitch width.
- Raises
UserWarning – Width outside of [-49.8, 49.8]. The value is rounded to one of these. (CW-lite/pro only)
- GlitchSettings.offset
The offset from a rising clock edge to a glitch pulse rising edge.
For CW-Husky, offset is expressed as the number of phase shift steps. Minimum offset is obtained at 0 (rising edge of glitch aligned with rising edge of glitch source clock). At scope.glitch.phase_shift_steps/2, the glitch rising edge is aligned with the glitch source clock falling edge. Negative values are allowed, but -x is equivalent to scope.glitch.phase_shift_steps-x. The setting rolls over (+x is equivalent to scope.glitch.phase_shift_steps+x). Run the notebook in jupyter/demos/husky_glitch.ipynb to visualize glitch settings.
For other capture hardware (CW-lite, CW-pro), offset is expressed as a percentage of one period. A pulse may begin anywhere from -49.8% to 49.8% away from a rising edge, allowing glitches to be swept over the entire clock cycle.
Warning
very large negative offset <-45 may result in double glitches (CW-lite/pro only).
- Getter
Return an int (Husky) or float (CW-lite/pro) with the current glitch offset.
- Setter
Set the glitch offset. For CW-lite/pro, the new value is rounded to the nearest possible offset.
- Raises
UserWarning – value outside range [-50, 50] (value is rounded) (CW-lite/pro only)
- GlitchSettings.clk_src
The clock signal that the glitch DCM is using as input.
- This DCM can be clocked from three different sources:
“target”: The HS1 clock from the target device (can also be AUX clock for Husky)
“clkgen”: The CLKGEN DCM output (N/A for Husky)
“pll”: Husky’s on-board PLL clock (Husky only)
- Getter
Return the clock signal currently in use
- Setter
Change the glitch clock source
- Raises
ValueError – New value not one of “target”, “clkgen” or “pll”
- GlitchSettings.phase_shift_steps¶
The number of phase shift steps per target clock period. Husky only. To change, modify clock.pll.update_fpga_vco()
- Getter
Returns the number of steps.
- GlitchSettings.mmcm_locked¶
Husky only. Whether the Xilinx MMCMs used to generate glitches are locked or not.
Pro/Husky Only Featuers¶
SAD¶
Communicates with and drives the Sum of Absolute Differences module on the ChipWhisperer Pro.
Example for triggering off of some previously collected scope data:
scope.SAD.reference = trace.wave[1000:1000+128] scope.SAD.threshold = 5000 scope.SAD.start() scope.trigger.module = "SAD" scope.adc.basic_mode = "rising_edge" #can now capture as normal trace = cw.capture_trace(scope, target, text, key)
- class ChipWhispererSAD(oa)¶
Communicates with the SAD module inside the CW Pro
This submodule is only available on the ChipWhisperer1200 Pro
Example:
trace, ret = cw.capture_trace(scope, data, text, key) cw.SAD.reference = trace[400:528] cw.SAD.threshold = 1000 cw.SAD.start() cw.trigger.module = 'SAD' #SAD trigger active trace, ret = cw.capture_trace(scope, data, text, key)
- check_status()¶
Check if the SAD module is running & outputting valid data
- getThreshold()¶
Get the threshold. When the SAD output falls below this threshold the system triggers
- property reference¶
Set the reference data for the SAD Trigger.
The reference must be 128 samples long. Through this interface, it is represented as a numpy array of floats between -0.5 and 0.5 (the same as trace data).
- Getter
Gets the currently set SAD reference
- Setter
Sets the SAD reference
- Raises
ValueError – Data not 128 samples long
- reset()¶
Reset the SAD hardware block. The ADC clock must be running!
- setRefWaveform(dataRef)¶
Download a reference waveform. Resets the SAD module & starts it again after loading the new data. ADC Clock must be running!
- setThreshold(threshold)¶
Set the threshold. When the SAD output falls below this threshold the system triggers
- start()¶
Start the SAD algorithm, which causes the reference data to be loaded from the FIFO
- property threshold¶
The threshold for the SAD trigger.
The threshold has a maximum value of 100 000. You should set the reference waveform via SAD.reference before setting this value.
- Getter
Return the current threshold
- Setter
Set the current threshold
- Raises
ValueError – The user attempted to set a threshold above 100 000
IOError – User attempted to set the threshold before the reference waveform.
DecodeIO¶
Communicates with and drives the Digital Pattern Match module on the ChipWhisperer Pro.
Basic usage for triggering on
'rn'
:# assuming setup scope scope.trigger.triggers = 'tio1' scope.trigger.module = 'DECODEIO' scope.decode_IO.rx_baud = 38400 scope.decode_IO.decode_type = 'USART' scope.decode_IO.trigger_pattern = ['r', '\n']
- class ChipWhispererDecodeTrigger(oa)¶
Communicates and drives the Digital Pattern Match module inside the FPGA.
Basic Usage for triggering on ‘r’:
#assuming setup scope: scope.trigger.triggers = 'tio1' scope.trigger.module = 'DECODEIO' scope.decode_IO.rx_baud = 38400 scope.decode_IO.decode_type = 'USART' scope.decode_IO.trigger_pattern = ['r']
- property decode_type¶
Type of data to trigger off of. Only ‘USART’ for now.
- Getter
Gets the current decode_type
- Setter
Sets the decode_type
- Raises
ValueError – User attempted to set decode_type to something other than ‘USART’
- get_triggerpattern()¶
Get the trigger pattern, where ‘XX’ is used for don’t-care bytes
- property rx_baud¶
The baud rate of the serial data to trigger off of
The baud rate can be between 0 and 1E6
- Getter
Gets the set baud rate
- Setter
Sets the baud rate
- Raises
ValueError – User attempted to set baud rate out of bounds
- set_triggerpattern(tp)¶
Set the trigger pattern - expects to be passed a string which will be evaluated, or a list directly
tp should be a string which evaluates to a list, like “[‘r’, 0x00, 0x12, ‘a’]
- property trigger_pattern¶
The pattern to trigger off of.
- Getter
Get the currently set trigger pattern
- Setter
Sets the trigger pattern. Expects a list of ASCII characters/ints. ints in this list are equivalent to their corresponding ASCII representation. For example, [0x10] is the same as [’\n’].
Warns the user if they try to set an incorrect pattern.
Example to trigger off of
'rn'
:scope.decode_IO.trigger_pattern = ['r', 0x10]
Husky Only Features¶
scope.LA¶
Built in logic analyzer for visualizing internal FPGA signals. Notably can be used for visualizing glitch parameters, as in the Husky Glitch Notebook
- class LASettings(oaiface, mmcm, scope)¶
Husky logic analyzer settings. For accessing recorded glitch generation, IO, and USERIO signals.
- property capture_depth¶
Number of bits captured for each signal.
- Parameters
depth (int) – capture <depth> samples of each signal. 16-bit value, in range [1, 16376].
- property capture_group¶
Sets which group of signals are captured.
There are three groups. The signals captured for each group are as follows: ‘glitch’ (group 0):
glitch output
source clock of glitch module
glitch internal MMCM1 (offset) output
glitch internal MMCM2 (width) output
glitch go internal signal
capture trigger
glitch enable
manual glitch trigger in source clock domain (e.g. signal 1 of this group)
glitch trigger in MMCM1 clock domain
‘CW 20-pin’ (group 1):
IO1
IO2
IO3
IO4
HS1
HS2
AUX MCX
TRIG MCX
ADC sampling clock
‘USERIO 20-pin’ (group 2):
D0
D1
D2
D3
D4
D5
D6
D7
CK
‘trigger debug’ (group 3) ‘internal trace’ (group 4)
- Getter
Return the capture group currently in use.
- Setter
Change the capture group.
- Raises
ValueError – invalid capture group.
- property clk_source¶
The clock signal that the logic analyzer is using to generate its sampling clock.
- There are three different sources:
“target”: The HS1 clock from the target device.
“clkgen”: The CLKGEN DCM output.
“pll”: Husky’s on-board PLL clock.
- Getter
Return the clock signal currently in use
- Setter
Change the clock source
- Raises
ValueError – New value not one of “target”, “clkgen” or “pll”
- property clkgen_enabled¶
Controls whether the Xilinx MMCM used to generate the samplign clock is powered on or not. 7-series MMCMs are power hungry. In the Husky FPGA, MMCMs are estimated to consume close to half of the FPGA’s power. If you run into temperature issues and don’t require the logic analyzer or debug trace functionality, power down this MMCM.
- property downsample¶
Downsample setting.
- Parameters
downsample (int) – capture every <downsample> samples. 16-bit value, in range [1, 2**16].
- property enabled¶
Controls whether this block is active for recording data. The LA and trace components share the same FPGA storage, so they cannot be simultaneously enabled.
- property errors¶
Indicate whether internal FPGA errors have occurred. Write to clear.
- static extract(raw, index)¶
- fifo_empty()¶
Returns True if the capture FIFO is empty, False otherwise.
- property locked¶
Return whether the sampling clock MMCM is locked (True or False).
- property oversampling_factor¶
Multiplier for the sampling clock. Can be fractional, but an integer is probably what you want. Whether the desired oversampling factor can be achieved depends on the source clock frequency; a warning is issued if it can’t.
- Getter
Return the actual oversampling factor.
- Setter
Set the desired oversampling factor.
- property present¶
Return whether the logic analyzer functionality is present in this build (True or False). If it is not present, none of the functionality of this class is available.
- read_capture(source, length=None)¶
Returns captured data for specified signal source. What you get depends on the capture group; see the capture_group documentation.
- Parameters
source (int) – signal to read
length (int) – number of byte to read. If unspecified, returns the full capture size (which is implementation-dependent and can be learned from capture_depth)
- Returns
Numpy array of binary values.
- Raises
ValueError – invalid source
- read_capture_data(check_empty=False)¶
Read captured data.
Returns: List of captured entries. Each list element is itself a 3-element list, containing the 3 bytes that make up a capture entry. Use extract() to parse.
- reset_MMCM()¶
Reset the sampling clock’s MMCM.
- property sampling_clock_frequency¶
Report the actual sampling clock frequency.
- trigger_now()¶
Trigger the capture manually.
- property trigger_source¶
The trigger used by the logic analyzer to capture.
- There are several different sources:
- “glitch”: The internal glitch enable trigger, one cycle earlier than the
glitch output seen when scope.glitch.output = ‘enable_only’. This signal is in the MMCM1 clock glitch domain.
“capture”: The internal ADC capture trigger.
- “glitch_source”: The internal manual glitch trigger in the source or target clock
domain (as per scope.glitch.clk_src), which accounts for scope.glitch.ext_offset but not scope.glitch.offset. Should only be used with scope.glitch.trigger_src = ‘manual’; may not fire reliably with other settings.
“glitch_trigger”: The internal glitch trigger in the MMCM1 clock domain.
“HS1”: The HS1 input clock.
In addition, capture can be triggered manually, irrespective of the trigger_source setting, by calling scope.LA.trigger_now()
- Getter
Return the trigger source currently in use
- Setter
Change the trigger source
- Raises
ValueError – New value not one of the options listed above.
scope.ADS4128Settings¶
- class ADS4128Settings(oaiface)¶
Husky ADS4128 ADC settings. Mostly for testing, not needed in normal use.
- adc_reset()¶
Resets the ADC. Note this is done by the FPGA - see reg_husky_adc.v
- property hi_perf¶
High performance mode setting. Valid values are 0 (high performance off), 1, and 2. See ADS4128 datasheet for more information.
- Getter
Return the high performance mode setting.
- Setter
Set the high performance mode setting.
- property low_speed¶
Whether the ADC is set to “low speed” operation; recommended for sampling rates below 80 MS/s.
- Getter
Return whether the ADC is set to low speed mode.
- Setter
Set the low speed mode.
- property mode¶
The current mode of the ADC.
- Getter
Return the current ADC operating mode (“normal” or “test ramp”)
- Setter
Set the operating mode.
- Raises
ValueError – if mode not one of “normal” or “test ramp”
scope.LEDs¶
- class LEDSettings(oaiface)¶
Set source of Husky front-panel LEDs
- property setting¶
Front-panel LED sources.
default: green=armed, blue=capture, top red=PLL lock fail, bottom red=glitch
green: USB clock heartbeat, blue=CLKGEN clock heartbeat
green: ADC sampling clock heartbeat, blue=PLL reference clock heartbeat
green: PLL clock heartbeat, blue=external clock change detected
In all cases, blinking red lights indicate a temperature, voltage, or sampling error (see scope.XADC.status and scope.adc.errors for details), whlie blinking green and blue lights indicate that a frequency change was detected on the external clock input (and that scope.clock should be updated to account for this).
scope.errors¶
- class HuskyErrors(oaiface, XADC, adc, clock, trace)¶
Gather all the Husky error sources in one place. Use scope.errors.clear() to clear them.
scope.userio¶
- class USERIOSettings(oaiface)¶
Control Husky’s USERIO (20-pin front connector) interface.
- property direction¶
Set the direction of the USERIO data pins (D0-D7) with an 8-bit integer, where bit <x> determines the direction of D<x>; bit x = 0: D<x> is an input to Husky. bit x = 1: D<x> is driven by Husky. When scope.userio.mode is not “normal”, then this setting is controlled by the FPGA and cannot be changed by the user. Use with care.
- property drive_data¶
8-bit data to drive on the USERIO data bus.
- property fpga_mode¶
When scope.userio.mode = ‘fpga_debug’, selects which FPGA signals are routed to the USERIO pins. See cwhusky_top.v for definitions.
- property mode¶
Set mode for USERIO pins: “normal”: as defined by scope.userio.direction. “trace”: for target trace capture. “target_debug_jtag”: for target debugging with ChipWhisperer using MPSSE in JTAG mode “target_debug_swd”: for target debugging with ChipWhisperer using MPSSE in SWD mode “fpga_debug”: for FPGA debug (look to cwhusky_top.v for signal definitions).
- property status¶
Returns current value of header pins. LSB=D0, MSB=CK.
scope.XADC¶
- class XADCSettings(oaiface)¶
Husky FPGA XADC temperature and voltage monitoring.
- get_temp(addr=0)¶
Read XADC temperature. :param addr: DRP address (0: current; 32: max; 36: min) :type addr: int
- Returns
Temperature in celcius (float).
- get_vcc(rail='vccint')¶
Read XADC vcc. :param rail: ‘vccint’, ‘vccaux’, or ‘vccbram’ :type rail: string
- Returns
voltage (float).
- property max_temp¶
Returns the highest observed FPGA temperature.
- property ot_temp_reset¶
FPGA over-temperature reset. When the FPGA temperature returns below this value, the error condition triggered by ot_temp_trigger is cleared.
- property ot_temp_trigger¶
FPGA over-temperature trigger. If the FPGA temperature exceeds this value, an error is flagged, and all clock-generating modules are shut down until the temperature returns below ot_temp_reset (since they are very power hungry). Read-only.
- set_temp(temp, addr=0)¶
Set XADC temperature thresholds. :param addr: DRP address :type addr: int :param temp: temperature threshold [celcius] :type temp: float
- Returns
Temperature in celcius (float).
- property status¶
Read XADC alarm status bits :Getter: Returns status string.
- Setter
Clear the status error bits (they are sticky).
- property temp¶
Returns the current FPGA temperature.
- property temp_reset¶
FPGA user temperature reset. When the FPGA temperature returns below this value, the error condition triggered by temp_trigger is cleared.
- property temp_trigger¶
FPGA user temperature trigger. If the FPGA temperature exceeds this value, an error is flagged, and all clock-generating modules are shut down until the temperature returns below temp_reset (since they are very power hungry).
- property vccaux¶
Returns the current VCCaux value.
- property vccbram¶
Returns the current VCCbram value.
- property vccint¶
Returns the current VCCint value.
ChipWhisperer Nano Scope¶
Supported scopes:
- class CWNano¶
CWNano scope object.
This class contains the public API for the CWNano hardware. It includes specific settings for each of these devices.
To connect to one of these devices, the easiest method is:
import chipwhisperer as cw scope = cw.scope(type=scopes.CWNano)
Some sane default settings can be set using:
scope.default_setup()
For more help about scope settings, try help() on each of the ChipWhisperer scope submodules (scope.adc, scope.io, scope.glitch):
Inherits from
chipwhisperer.capture.api.cwcommon.ChipWhispererCommonInterface
- arm()¶
Arm the ADC, the trigger will be GPIO4 rising edge (fixed trigger).
- capture(poll_done=False)¶
Raises IOError if unknown failure, returns ‘True’ if timeout, ‘False’ if no timeout
- con(sn=None, **kwargs)¶
Connects to attached chipwhisperer hardware (Nano)
- Parameters
sn (str) – The serial number of the attached device. Does not need to be specified unless there are multiple devices attached.
- Returns
True if connection is successful, False otherwise.
- default_setup()¶
Sets up sane capture defaults for this scope
7.5MHz ADC clock
7.5MHz output clock
5000 capture samples
tio1 = serial rx
tio2 = serial tx
glitch module off
New in version 5.1: Added default setup for CWNano
- dis()¶
Disconnects the current scope object.
- Returns
True if the disconnection was successful, False otherwise.
- get_last_trace(as_int=False)¶
Return the last trace captured with this scope.
Can return traces as floating point values (
as_int=False
) or as integers.Floating point values are scaled and shifted to be between -0.5 and 0.5.
Integer values are raw readings from the ChipWhisperer ADC. The ChipWhisperer-Lite has a 10-bit ADC, the Nano has an 8-bit ADC, and the Husky can read either 8-bits or 12-bits of ADC data.
- Parameters
as_int (bool) – If False, return trace as a float. Otherwise, return as an int.
- Returns
Numpy array of the last capture trace.
Changed in version 5.6.1: Added as_int parameter
adc¶
- class ADCSettings(usb)¶
- property clk_freq¶
Set the frequency for CLKOUT. Will be rounded to nearest possible values, check results to see programmed value. Set to ‘None’ for disabling (High-Z) output.
- Getter
Returns the actual frequency for CLKOUT
- Setter
Sets CLKOUT to the nearest possible value.
- property clk_src¶
ADC Clock source.
- Getter
Returns ‘int’ or ‘ext’ based on the clock source.
- Setter
(str) Set the ADC clock source to either internal or external: (‘int’ or ‘ext’)
- property samples¶
Number of samples to store.
io¶
- class GPIOSettings(usb)¶
- property cdc_settings¶
Check or set whether USART settings can be changed via the USB CDC connection
i.e. whether you can change USART settings (baud rate, 8n1) via a serial client like PuTTY
- Getter
An array of length two for two possible CDC serial ports (though only one is used)
- Setter
Can set either via an integer (which sets both ports) or an array of length 2 (which sets each port)
Returns None if using firmware before the CDC port was added
- property clkout¶
“Set the frequency for CLKOUT. Will be rounded to nearest possible values, check results to see programmed value. Set to ‘None’ for disabling (High-Z) output.
- property nrst¶
The state of the NRST pin.
See pdic for more information.
- property pdic¶
The state of the PDIC pin output pin.
- This is a GPIO pin. The following values are allowed:
“high” / True: logic 1
“low” / False: logic 0
“disabled” / “default” / “high_z” / None: undriven
- Getter
Return one of “high”, “low”, or “high_z”
- Setter
Set the pin’s state Raises: ValueError if new state not listed above
- property pdid¶
The state of the PDID pin.
See pdic for more information.
- property tio1¶
The function of the Target IO1 pin.
- TIO1 can be used for the following functions:
“serial_rx”: UART input
Default value is “serial_rx”.
- Getter
Return None
- Setter
Set the Target IO1 mode. Raises: ValueError if new value is not one of the above modes
- property tio2¶
The function of the Target IO2 pin.
- TIO2 can be used for the following functions:
“serial_tx”: UART output
Default value is “serial_tx”.
- Getter
Return None
- Setter
Set the Target IO2 mode. Raises: ValueError if new value is not one of the above modes
- property tio3¶
The function of the Target IO3 pin.
- TIO3 can be used for the following functions:
“high_z” / None: High impedance input
“gpio_low” / False: Driven output: logic 0
“gpio_high” / True: Driven output: logic 1
“gpio_disabled”: Driven output: no effect
Default value is “high_z”.
- Getter
Return one of the above strings
- Setter
Set the Target IO3 mode. Raises: ValueError if new value is not one of the above modes
- property tio4¶
The function of the Target IO4 pin.
- TIO4 can be used for the following functions:
“high_z” / None: High impedance input
Default value is “high_z”. Typically, this pin is used as a trigger input.
- Getter
Return None
- Setter
Set the Target IO4 mode Raises: ValueError if new value is not one of the above modes
glitch¶
Common Scope Attributes¶
The following methods and attributes are common to all scopes, as well as the CW305/CW310:
- class ChipWhispererCommonInterface¶
- enable_MPSSE(enable=True)¶
Enable or disable MPSSE mode
- check_feature(name, raise_exception=False)¶
Check if a feature is available on this ChipWhisperer
- feature_list()¶
Returns a list of supported features that depend on device/firmware version
- Return type
List
[str
]
- _getNAEUSB()¶
- Return type
NAEUSB
- get_serial_ports()¶
Get serial ports associated with a ChipWhisperer
New in version 5.5: Add get_serial_ports()
- Return type
Optional
[List
[Dict
[str
,int
]]]
- upgrade_firmware()¶
Attempt a firmware upgrade. See https://chipwhisperer.readthedocs.io/en/latest/firmware.html for more information.
New in version 5.6.1: Improved programming interface
- reset_sam3u()¶
Reset the ChipWhisperer’s microcontroller
New in version 5.6.1: Add common cw interface
- latest_fw¶
Get the newest firmware as a dict with elements major, minor and debug
- Return type
Dict
[str
,int
]
- latest_fw_str¶
- Return type
str
- fw_version¶
Get current firmware version as a dict with elements major, minor and debug
- Return type
Dict
[str
,int
]
- fw_version_str¶
A string of the firmware version:
'x.y.z'
- Return type
str
- sam_build_date¶
The date the SAM3U firmware was built on
New in version 5.6.1: Added sam build date to chipwhisperer
- Return type
str
- sn¶
The USB serial number of this scope.
Can be passed to cw.scope() to specify which ChipWhisperer to connect to
- Return type
str
Firmware Update¶
A simplified method of updating firmware has been added as of ChipWhisperer 5.6.0. This new method is documented at Updating Firmware.
For versions 5.5.2 and below, you must follow the directions below:
See also
You can also use the BOSSA BOSSA utiltiy to reflash the SAM3U firmware. If you need to build it from source, NewAE keeps a slightly modified version of the source at https://github.com/newaetech/BOSSA. This utility does NOT support the CWNano.
- class SAMFWLoader(scope=None, logfunc=<built-in function print>)¶
Object for easy reprogramming of ChipWhisperers
See https://chipwhisperer.readthedocs.io/en/latest/firmware.html for information on how to update.
Can autoprogram if the ChipWhisperer’s firmware has not already been erased.
Autoprogram Example:
Attach the scope part of the hardware to your computer.
Connect to the scope using:
import chipwhisperer as cw # Connect to scope scope = cw.scope() # If using CW305, connect to target as well # Can ignore msg about no bitstream target = cw.target(None, cw.targets.CW305)
Call the auto_program() method:
programmer = cw.SAMFWLoader(scope=scope) # if CW305 # programmer = cw.SAMFWLoader(scope=target) programmer.auto_program()
Example
Attach the scope part of the hardware to your computer.
Connect to the scope using:
import chipwhisperer as cw # Connect to scope scope = cw.scope() # If using CW305, connect to target as well # Can ignore msg about no bitstream target = cw.target(None, cw.targets.CW305)
Place the hardware in bootloader mode using:
# use created scope object from previous step programmer = cw.SAMFWLoader(scope=scope) # or CW305 target object programmer = cw.SAMFWLoader(scope=target) # WARNING: this will erase the firmware on the device # and make it unusable until reprogrammed. programmer.enter_bootloader(really_enter=True)
Unplug then plug in the hardware into your computer again. The device should be shown as BOSSA in the device manager on Windows. Make not of the port number the BOSSA device is attached to (for example: COM1, or COM2, and so on)
Program the SAM3U with:
import chipwhisperer as cw programmer = cw.SAMFWLoader(scope=None)
Two methods:
Using the firmware_path:
# the firmware file is included with chipwhisperer # and is the .bin file from the FW build # (ChipWhisperer Lite) chipwhisperer\hardware\capture\chipwhisperer-lite\sam3u_fw\SAM3U_VendorExample\Debug # directory. programmer.program(<port>, <path to firmware file>)
Using the hardware_type (recommended):
programmer.program(<port>, hardware_type='cwlite') programmer.program(<port>, hardware_type='cwnano') programmer.program(<port>, hardware_type='cw305') programmer.program(<port>, hardware_type='cw1200')
On Linux instead of ‘COM#’ use the Linux equivalent (usually /dev/ttyACM# or /dev/ttyUSB#)
Once the programming is done. Unplug then plug in the hardware into your computer again. The device should show up as a ChipWhisperer again.
- enter_bootloader(really_enter=False)¶
Enters the bootloader of the ChipWhisperer by erasing the flash
Only use this if you want to erase the scope’s firmware (i.e. the ChipWhisperer Lite). This does NOT erase the firmware of a target ( i.e. an STM32 target). Will raise a Warning the first time an erase is attempted and really_enter=False.
- Parameters
really_enter (bool, optional) – If True, enter the bootloader without ever raising a warning. If False, raise a warning if this is the user’s first time calling it.
- Raises
Warning – really_enter=False and user hasn’t seen this warning before
- program(port, fw_path=None, hardware_type=None, bypass_warning=False)¶
Program the ChipWhisperer with new firmware.
- Parameters
port (str) – Serial port that the ChipWhisperer bootloader is on
fw_path (str) – Path to firmware, if specified leave out hardware type.
hardware_type (str) – The type of hardware that you want to program. If specified leave out fw_path. Valid types: (cwlite, cwnano, cw305, cw1200)
- Returns
True if programming succeeded, False if it didn’t
- auto_program()¶
Erase and program firmware of ChipWhisperer
Autodetects comport and hardware type.