.. _api-scope: ********* 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 :func:`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: * :ref:`api-scope-openadc` (Lite, Pro, Husky) * :ref:`api-scope-cwnano` (Nano) These scope objects also inherit common methods from :ref:`api-scope-common`. .. autodata:: chipwhisperer.scope :annotation: chipwhisperer.scope() As of ChipWhisperer 5.6.2, ChipWhisperer can find all connected devices: .. autodata:: chipwhisperer.list_devices :annotation: chipwhisperer.list_devices() .. _api-scope-openadc: OpenADC Scope ============= Supported scopes: * :doc:`Capture/ChipWhisperer-Lite` * :doc:`Capture/ChipWhisperer-Pro` * :doc:`Capture/ChipWhisperer-Husky` Usage examples: * `Power Analysis `_ * `Glitch `_ * `Pro features `_ * `Husky glitching `_ .. autoclass:: chipwhisperer.scopes.OpenADC :members: :exclude-members: enable_MPSSE, upgrade_firmware scope.gain ---------- Class to control ADC gain. .. autoclass:: chipwhisperer.capture.scopes._OpenADCInterface.GainSettings :members: scope.adc --------- Class to control non-gain, non-clock ADC settings. .. autoclass:: chipwhisperer.capture.scopes._OpenADCInterface.TriggerSettings :members: :exclude-members: stream_mode, segment_cycles, segment_cycle_counter_en, first_error, first_error_state, errors, segments, bits_per_sample scope.adc **(Pro/Husky Only)** ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The following :code:`scope.adc` members are only available on ChipWhisperer-Husky, ChipWhisperer-Pro, or both. .. autoclass:: chipwhisperer.capture.scopes._OpenADCInterface.TriggerSettings :noindex: .. autoproperty:: chipwhisperer.capture.scopes._OpenADCInterface.TriggerSettings.stream_mode .. autoproperty:: chipwhisperer.capture.scopes._OpenADCInterface.TriggerSettings.segment_cycles .. autoproperty:: chipwhisperer.capture.scopes._OpenADCInterface.TriggerSettings.segment_cycle_counter_en .. autoproperty:: chipwhisperer.capture.scopes._OpenADCInterface.TriggerSettings.first_error_state .. autoproperty:: chipwhisperer.capture.scopes._OpenADCInterface.TriggerSettings.errors .. autoproperty:: chipwhisperer.capture.scopes._OpenADCInterface.TriggerSettings.segments .. autoproperty:: chipwhisperer.capture.scopes._OpenADCInterface.TriggerSettings.bits_per_sample scope.clock ----------- scope.clock **(Lite/Pro Only)** ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. warning:: ChipWhisperer-Lite/Pro only. See :attr:`scope.clock (Husky) ` for Husky clock documentation. Class to control target/ADC clocks. A block diagram of the clock module is shown below: .. thumbnail:: figures/cwlitepro_clock.png .. autoclass:: chipwhisperer.capture.scopes._OpenADCInterface.ClockSettings :members: scope.clock **(Husky Only)** ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. autoclass:: chipwhisperer.capture.scopes.cwhardware.ChipWhispererHuskyClock.ChipWhispererHuskyClock :members: scope.io -------- Module to control IO pins. .. autoclass:: chipwhisperer.capture.scopes.cwhardware.ChipWhispererExtra.GPIOSettings :members: scope.trigger ------------- Basic trigger control module. .. autoclass:: chipwhisperer.capture.scopes.cwhardware.ChipWhispererExtra.TriggerSettings :members: scope.trigger **(Pro Only)** ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. autoclass:: chipwhisperer.capture.scopes.cwhardware.ChipWhispererExtra.ProTrigger :members: scope.trigger **(Husky Only)** ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. autoclass:: chipwhisperer.capture.scopes.cwhardware.ChipWhispererExtra.HuskyTrigger :members: scope.glitch ------------ Module to control glitching. A block diagram of the module is shown below: .. thumbnail:: figures/cwlitepro_glitch.png .. note:: This diagram is slightly inaccurate because the "offset" parameter also affects the glitch output in "enable_only" mode. :code:`scope.glitch` controls the shape of the glitch for **both voltage and clock glitching**. Whether this glitch goes out into the outside world as a voltage glitch or a clock glitch depends on :class:`scope.io ` settings (as illustrated by the figure above). This also means that some :code:`scope.glitch` settings are sensible for voltage glitching but not clock glitching, or vice-versa. Take the time to go through our `glitch notebooks `_ to learn how to glitch with your ChipWhisperer device. .. autoclass:: chipwhisperer.capture.scopes.cwhardware.ChipWhispererGlitch.GlitchSettings :members: :exclude-members: enabled, mmcm_locked, phase_shift_steps, actual_num_glitches, reset_glitch_counter, num_glitches scope.glitch **(Husky Only)** ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The following attributes are only available on, or differ substantially on the ChipWhisperer-Husky .. autoclass:: chipwhisperer.capture.scopes.cwhardware.ChipWhispererGlitch.GlitchSettings :noindex: .. autoattribute:: chipwhisperer.capture.scopes.cwhardware.ChipWhispererGlitch.GlitchSettings.enabled .. autoattribute:: chipwhisperer.capture.scopes.cwhardware.ChipWhispererGlitch.GlitchSettings.width :noindex: .. autoattribute:: chipwhisperer.capture.scopes.cwhardware.ChipWhispererGlitch.GlitchSettings.offset :noindex: .. autoattribute:: chipwhisperer.capture.scopes.cwhardware.ChipWhispererGlitch.GlitchSettings.clk_src :noindex: .. autoattribute:: chipwhisperer.capture.scopes.cwhardware.ChipWhispererGlitch.GlitchSettings.phase_shift_steps .. autoattribute:: chipwhisperer.capture.scopes.cwhardware.ChipWhispererGlitch.GlitchSettings.mmcm_locked .. autoattribute:: chipwhisperer.capture.scopes.cwhardware.ChipWhispererGlitch.GlitchSettings.num_glitches .. autoattribute:: chipwhisperer.capture.scopes.cwhardware.ChipWhispererGlitch.GlitchSettings.actual_num_glitches .. automethod:: chipwhisperer.capture.scopes.cwhardware.ChipWhispererGlitch.GlitchSettings.reset_glitch_counter Pro Only Features ----------------------- scope.SAD ^^^^^^^^^^^^^^ .. autoclass:: chipwhisperer.capture.scopes.cwhardware.ChipWhispererSAD.ChipWhispererSAD :members: scope.decode_IO ^^^^^^^^^^^^^^^ .. autoclass:: chipwhisperer.capture.scopes.cwhardware.ChipWhispererDecodeTrigger.ChipWhispererDecodeTrigger :members: .. _api-scope-husky: Husky Only Features ------------------- scope.SAD ^^^^^^^^^^^^^^ .. autoclass:: chipwhisperer.capture.scopes.cwhardware.ChipWhispererSAD.HuskySAD :members: scope.trace ^^^^^^^^^^^^^^^^^ .. autoclass:: chipwhisperer.capture.trace.TraceWhisperer.TraceWhisperer :members: scope.UARTTrigger ^^^^^^^^^^^^^^^^^ UART Pattern Matching Trigger. Must set :code:`scope.trigger.module = 'UART'` to select this trigger. .. autoclass:: chipwhisperer.capture.trace.TraceWhisperer.UARTTrigger :members: 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 `_. .. autoclass:: chipwhisperer.capture.scopes.cwhardware.ChipWhispererHuskyMisc.LASettings :members: scope.ADS4128Settings ^^^^^^^^^^^^^^^^^^^^^ .. autoclass:: chipwhisperer.capture.scopes.cwhardware.ChipWhispererHuskyMisc.ADS4128Settings :members: scope.LEDs ^^^^^^^^^^^^^^^^^ .. autoclass:: chipwhisperer.capture.scopes.cwhardware.ChipWhispererHuskyMisc.LEDSettings :members: scope.errors ^^^^^^^^^^^^ .. autoclass:: chipwhisperer.capture.scopes.cwhardware.ChipWhispererHuskyMisc.HuskyErrors :members: scope.userio ^^^^^^^^^^^^ .. autoclass:: chipwhisperer.capture.scopes.cwhardware.ChipWhispererHuskyMisc.USERIOSettings :members: .. autoclass:: chipwhisperer.capture.scopes.cwhardware.ChipWhispererHuskyMisc.USERIOPin :members: scope.bitbanger ^^^^^^^^^^^^^^^ .. autoclass:: chipwhisperer.capture.scopes.cwhardware.ChipWhispererHuskyBitBanger.BitBanger :members: .. autoclass:: chipwhisperer.capture.scopes.cwhardware.ChipWhispererHuskyBitBanger.OneWireHelper :members: .. autoclass:: chipwhisperer.capture.scopes.cwhardware.ChipWhispererHuskyBitBanger.SWDHelper :members: .. autoclass:: chipwhisperer.capture.scopes.cwhardware.ChipWhispererHuskyBitBanger.BitBangerPacket :members: scope.XADC ^^^^^^^^^^ .. autoclass:: chipwhisperer.capture.scopes.cwhardware.ChipWhispererHuskyMisc.XADCSettings :members: .. _api-scope-cwnano: ChipWhisperer Nano Scope ======================== Supported scopes: * :doc:`Capture/ChipWhisperer-Nano` .. autoclass:: chipwhisperer.scopes.CWNano :members: :exclude-members: enable_MPSSE, upgrade_firmware scope.adc --------- .. autoclass:: chipwhisperer.capture.scopes.cwnano.ADCSettings :members: scope.io --------- .. autoclass:: chipwhisperer.capture.scopes.cwnano.GPIOSettings :members: scope.glitch ------------ .. autoclass:: chipwhisperer.capture.scopes.cwnano.GlitchSettings :members: .. _api-scope-common: Common Scope Attributes ======================= The following methods and attributes are common to all scopes, as well as the CW305/CW310: .. autoclass:: chipwhisperer.capture.api.cwcommon.ChipWhispererCommonInterface .. automethod:: enable_MPSSE .. automethod:: check_feature .. automethod:: feature_list .. automethod:: _getNAEUSB .. automethod:: get_serial_ports .. automethod:: upgrade_firmware .. automethod:: reset_sam3u .. autoattribute:: latest_fw .. autoattribute:: latest_fw_str .. autoattribute:: fw_version .. autoattribute:: fw_version_str .. autoattribute:: sam_build_date .. autoattribute:: sn .. _api-scope-update: Firmware Update =============== A simplified method of updating firmware has been added as of ChipWhisperer 5.6.0. This new method is documented at :ref:`Updating_Firmware`. For versions 5.5.2 and below, you must follow the directions below: .. seealso:: You can also use the BOSSA `BOSSA `_ utility 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. .. autoclass:: chipwhisperer.capture.scopes.cwhardware.ChipWhispererSAM3Update.SAMFWLoader .. automethod:: enter_bootloader .. automethod:: program .. automethod:: auto_program