Accessing the Programmer

First, setup the ChipWhisperer as usual:

import chipwhisperer as cw
scope = cw.scope()
target = cw.target(scope)

Next, the AVR programmer can be accessed through the cw.programmers.AVRProgrammer object:

prog = cw.programmers.AVRProgrammer

Programming the Flash

Note to use the AVR programmer you may require a valid clock source for the AVR. It is suggested to use the default ChipWhisperer setup, which will generate a 7.37MHz clock:

scope.default_setup()

Note that NewAE's Notduino targets have the transmit and receive pins swapped compared to the usual targets. If you're using one of these targets, swap them using the API:

scope.io.tio1 = "serial_tx"
scope.io.tio2 = "serial_rx"

Next, try programming the device by calling cw.program_target():

cw.program_target(scope, prog, "<path to hex file")

The default SPI data rate for the programmer is too fast for devices which are running slower than 2 MHz. If programming a device with a clock source slower than 2 MHz, you will need to enable the "Slow Clock Mode". In "Slow Clock Mode" the entire SAM3U and FPGA clock is changed from 96 MHz to 12 MHz. Note the default fuse bytes for a virgin ATMega328P result in a 1 MHz clock, so you will need to use "slow clock mode" to program the correct fuse bytes, after which point you will not need to use "slow clock mode".

To enable slow clock mode, call program_target with an additional slow_clock = True parameter:

cw.program_target(scope, prog, "<path to hex file", slow_clock=True)

note

The 'slow clock mode' is used to provide a slower SPI clock than would otherwise be possible. When switching into 'slow clock mode' it will cause all DCM blocks in the FPGA to become unlocked. You will need to reset the DCM blocks, or simply call default_setup() again (this will reset the serial pins, so you'll have to swap them again if you're using a Notduino target).

Programming the Fuses

By default the AVR programmer allows you to modify the LOW fuse byte only, as this byte controls the clock source selection. To change the value of the fuse byte, you'll need to manually setup the programmer:

avr_programmer = prog(slow_clock=False) #call with slow_clock = True to enable the slow clock
avr_programmer.scope = scope
avr_programmer.open()
avr_programmer.find()

Once that's accomplished, the readFuse() and writeFuse() methods can be used to read and write the fuse bits, respectively:

fuse_vals = avr_programmer.readFuse(<value>)
avr_programmer.writeFuse(<value>, <lfuse>)

with <value> corresponding to one of the following: "low", "high", or "extended".

See an Online Fuse Calculator to better understand what the values mean.

tip

If programming a virgin ATMega328P device, the default low-fuse value of 62 results in the internal 8 MHz oscillator being divided down to 1 MHz. Any external clock is ignored.

The low fuse byte must be changed to D0 to use the external clock provided by the ChipWhisperer toolchain.

Troubleshooting

If you run into issues when programming the AVR, try the following troubleshooting methods:

• Ensure the ChipWhisperer is outputting a clock if the target requires one.
• Ensure you have the serial pins the right way around
• Ensure the fuse bits are set correctly.

Checking Firmware Version

The firmware version is printed at start-up. You will see a line that looks like this indicating the version of the SAM3U Firmware:

Found CW-Lite, Serial Number = 442031204630xxxxxxxxxxx
SAM3U Firmware version = 0.11 b0
Programmed FPGA

If your firmware version is outdated, a warning will be printed. You can also see the firmware version in the Config CW Firmware dialog:

Note the main version is 0.11 in this example. The "b0" indicates a "build" number. Typically this will be "build 0", but special versions will use a different build number to indicate a variant of a regular version.

Upgrading Firmware

See https://chipwhisperer.readthedocs.io/en/latest/api.html#firmware-update for instructions on how to update the SAM3U firmware.

Linux usbserial module Workaround

There is an issue in some versions of Linux, where the SAM3U is not assigned a serial port when it enters bootloader mode. Here are some steps to resolve this issue (Note. this is not a permanent fix, you must go through these steps each time you put your ChipWhisperer into bootloader mode.). These steps assume you've already put ChipWhisperer into bootloader mode.

1. Unplug your ChipWhisperer (Leave unplugged until instructed otherwise)
2. Reboot your computer
3. Once logged in again, open a terminal session
4. Run this command: sudo modprobe usbserial vendor=0x3eb product=0x6124
5. Plug your ChipWhisperer back in
6. Check that a serial port is now open using: ls -l /dev/ttyUSB*

You should now be able to program the bootloader from ChipWhisperer Capture through the port you created

Manual Update

If the above instructions fail, there is no big problem. The SAM3U chip contains a hardware-resident bootloader. You may need to follow instructions on the Manual SAM3U Firmware Update page (including using BOSSA) if you are unable to use the automatic system that is part of ChipWhisperer-Capture.

Edge/Level

The edge/level detector can trigger on four different events:

• Trigger input is low (0)
• Trigger input is high (1)
• Trigger input had a rising edge (0 -> 1)
• Trigger input had a falling edge (1 -> 0)

This mode is suitable when the target is using one of the GPIO pins as a trigger signal - if you have control over the target's source code, let it output a rising edge when the encryption or other operation begins.

I/O Decoder

The I/O decoder examines the trigger signal, assumes that it is either UART or SPI traffic, and outputs a trigger signal when it detects a certain pattern on the line. In the capture software, the settings for this decoder are:

• Decode Type: Which type of traffic is being captured in the trigger signal? Might be USART or SPI data.
• Trigger Data: Which data are we searching for? This setting should be a list of bytes to be detected in order. For example, ['r', '0'] would detect the string "r0", and [0x07] would detect a bell character.
• Baud: What baud rate does this line use? This needs to be set manually.

When using this trigger mode, target IO1/IO2 are probably the best inputs to use: these are normally the serial TX and RX lines. It's possible to enable either one of these to trigger on sending or receiving data, respectively.

Sum of Absolute Differences (SAD)

Some targets don't have nice trigger signals to detect. Sad!

The Sum of Absolute Differences module has two 128 sample buffers. The FPGA stores the ADC's 128 most recent samples in one buffer and a fixed pattern in the other. Then, after every sample, it calculates

If this sum is below a fixed threshold, the output trigger signal will be set. This trigger module allows the ChipWhisperer to detect a specific pattern (for instance, an encryption operation) in a power trace without any other data.

The settings for the SAD module are:

• Point Range: The samples in the current trace to be used for the SAD module's fixed values. This range is forced to have a width of 128.
• Set SAD Reference from Current Trace: Sets the fixed 128 samples to the current selection.
• SAD Reference vs. Cursor: Shows the current output of the SAD calculation. Useful for setting the threshold - it's easy to capture a number of traces and check what typical values are for this SAD output.
• SAD Threshold: The trigger point for the SAD module. A value of 0 indicates a perfect match. If this threshold is too low, noise will stop the trigger from appearing; if it's too high, the scope will trigger at random offsets.

Note that this SAD module does not play well with downsampling: the inputs to the SAD buffer are not downsampled. This means that downsampled traces cannot be used as a reference. If you want to use this trigger type, set up your SAD trigger with downsampling turned off first.

Screen 1: Clock

The clock screen shows the status of the CLKGEN and ADC clocks along with the frequency counter.

TODO: picture

• CLKGEN: Current frequency of CLKGEN clock in kHz
  • Source: Input to CLKGEN DCM. Could be system clock or EXTCLK
  • DCM: Lock status of CLKGEN DCM
  • Reset DCM: Reset the CLKGEN output. Useful if clock has locked at the wrong frequency
• ADC Clock: Current ADC sampling rate in kHz
  • Source: Input to ADC DCM. Could be related to CLKGEN or EXTCLK
  • DCM: Lock status of ADC DCM
  • Reset DCM: Reset the ADC clock output
• Frequency Counter: Current frequency measured by the frequency counter
  • Source: Input to frequency counter. Could be either EXTCLK or CLKGEN

Screen 2: Routing

The routing screen shows the status of the various I/O pins.

TODO: picture

• Aux Output: Status of the aux SMA connections. Could be used as trigger input/output, glitch output, and/or clock output
• IO Pins: Status of each of the IO pins on the 20 pin connector. Possible values depend on pin
• Target Power State: Status of the 3.3 V output. Can be toggled here to reset target
• Target HS IO-Out: Signal connected to high-speed output (HS2). Could be CLKGEN, glitch module, or disabled

Screen 3: Trigger

The trigger screen shows the current settings for the trigger module and the ADC capture settings.

TODO: picture

• Trigger Pins: Whether each trigger input is enabled. Active inputs are highlighted
  • Mode: Trigger combination method. Could be AND, OR, or NAND
• Trigger Source: The trigger type in use. Active trigger module is highlighted
  • State: The current output level of the trigger module
• Trigger Mode: The ADC trigger type. Active mode is highlighted
• Samples:
  • Delay: Current ADC offset. This is the number of samples to wait after trigger before recording begins
  • Pre: Number of pre-trigger samples to be saved
  • Time: Delay, but converted into a time
  • Total: Number of samples to be recorded in total
• ADC gain:
  • Mode: Amplification type. Either low or high
  • Setting: Low noise amplifier gain level

Screen 4: Glitch

The glitch screen shows the current settings for the glitch module.

TODO: picture

• Clock Src: Input to the glitch module's clock. Active clock is highlighted
  • DCM: Lock status of the glitch module's DCM
• Glitch Setup:
  • Width: Duty cycle of glitch pulse, as a fraction of one period
  • Fine: Adjustment on width
  • Offset: Distance between clock rising edge and glitch pulse rising edge, as a fraction of one period
  • Fine: Adjustment on offset
• View: Schematic of glitch clock. Shows regular clock above (blue) and glitch module output below (black)
• Trigger Src: Input for glitch module. Active source is highlighted
• Trigger Setup:
  • Trigger: Cause a manual trigger. Has no effect unless trigger source is set to Manual
  • Offset: Number of cycles to wait before starting glitch pulses
  • Repeat: Number of consecutive pulses to generate
• Output Status
  • VCC: Status of glitching MOSFETs. Shows warning sign if VCC glitching is enabled
  • Cnt: Total number of glitch pulses generated