ChipSHOUTER® Python API Documentation

ChipSHOUTER® is an EMFI tool by NewAE Technology Inc. You can find more information about ChipSHOUTER at ChipSHOUTER.com. Note this documentation is only the Python API (which you install with pip install chipshouter) . You will likely need the full user manual on ChipSHOUTER.com, also mirrored in PDF to the ChipSHOUTER GIT Repo.

ChipSHOUTER API Documentation

PyChipSHOUTER allows you to / get options / set options via this API.

Using the ChipSHOUTER requires you to:
  1. configure settings:
    1. Capacitor bank voltage
    2. Pulse widths, settings (if using internal pulse generator)
  2. arm the device using:
    1. front-panel button, or
    2. sending arm command, or
    3. external IO pin on RJ12
  3. Triggering the pulse using:
    1. the pulse front-panel button, or
    2. the pulse command, or
    3. external IO pin on RJ12, or
    4. external hardware trigger

This API allows you to fine-tune the pulse settings, generate special waveforms, change voltage between 150-500V, and more!

Example

Below is an example of arming / pulse and then disarm.

>>> from chipshouter import ChipSHOUTER
>>> cs = ChipSHOUTER('COM12')
>>> print cs #get all values of device
>>> cs.voltage = 500
>>> cs.pulse.width = 180
>>> cs.armed = 1
>>> cs.pulse = 1
>>> cs.pat_wave = [0,1,1,1,0,0,0,0,0,0,1,1,1,1,1,0]
>>> cs.pat_enable = 1 #Turn on special pattern trigger
>>> cs.pulse = 1
>>> cs.armed = False #Can use true/false or 1/0

Scripting

Scripting ChipSHOUTER is recommended to deal with the expected error conditions. In particular, the ChipSHOUTER may reset during use due to the EMFI events. This can be detected as shown here:

from chipshouter import ChipSHOUTER
from chipshouter.com_tools import Reset_Exception
cs = ChipSHOUTER('COM4')

def setup_device:
    #Set any defaults you want
    cs.pulse.repeat = 1

    #Arm - add some delay for next stuff
    cs.armed = 1
    time.sleep(0.5)
    
    #Turn off sound if you want
    #cs.mute = True

while True:
    try:
        old = cs.voltage.set
        cs.voltage = random.randint(200, 500)
        cs.pulse = 1
    except Reset_Exception:
        print("Device rebooted!")
        time.sleep(5) #Need to wait after reboot!
        setup_device()
class chipshouter.chipshouter.ChipSHOUTER(comport)[source]

ChipSHOUTER object.

The ChipSHOUTER will attempt to connect when initialzed. This Object will contain all the status of the ChipSHOUTER connected. You will be able probe for status and control the status of the ChipSHOUTER.

Parameters:comport – (String): The serial port that the ChipSHOUTER is connected.
absent_temp

Configure maximum time the temperature sensors can be skipped for during trigger_safe mode. The temperature sensors cannot be read during pulse events, and the ChipSHOUTER keeps a timer of how old the last temperature reading is.

The timer is reset during routine self-checks (if triggers are not coming in quickly), or in response to the triggersafe command.

Parameters:value – (int) Time in seconds
api_version

This is the control of the armed status.

Returns (bool):
  • When read it will show True when armed, False if not.
Parameters:

(bool) (state) – Attempt to arm when True is passed in. Attempt to disarm when False is passed in.

arm_timeout

Arm timeout For safety reasons and to reduce heat generation, the ChipSHOUTER will automatically disarm after a specific number of minutes. If the time out occurs, the ChipSHOUTER will disarm and disable the high voltage circuitry.

The arm timer will be reset on every pulse trigger (internal or external). Thus if you are actively using the ChipSHOUTER it should not disarm on you.

NOTE Valid range is between 1 - 60 minutes

Parameters:state – (int): time in minutes for the timeout.
Returns (int):The arm timeout without triggering.
armed

This is the control of the armed status.

Returns (bool):
  • When read it will show True when armed, False if not.
Parameters:

(bool) (state) – Attempt to arm when True is passed in. Attempt to disarm when False is passed in.

clr_armed

Clear faults and then arm in one command.

Returns (bool):
  • When read it will show True when armed, False if not.
Parameters:

(bool) (state) – Attempt to arm when True is passed in. Attempt to disarm when False is passed in.

connect()[source]

This will disconnect the connection from the ChipSHOUTER.

Returns:(bool): Status of the connection, True if connected successfully. False if not.
disconnect()[source]

This will disconnect the connection from the ChipSHOUTER.

Returns:(bool): Status of the connection, True if connected successfully. False if not.
eeprom_write()[source]

Write settings to EEPROM

Originally, everytime config was changed, it was written to EEPROM, which could destroy EEPROM after a while.

Now only saves to EEPROM if this is called

emode

Pin 12 (external enable input) on the RJ12 connector can be ‘arm’ or ‘fire’.

In ‘arm’ mode:

When the external IO is set to high it will attempt arm the system.

Note: The system may not be armed because of a fault. The status Led on the connector will indicate the arm status.

When the external IO is set to low it will disarm the system.

The External IO reacts to the state change and not the static state. If the System fails to arm, to attempt again it needs to pull the line low and then high once again.

In ‘pulse’ mode:

When external IO is set high the pulse command is executed. This is equivalent to hitting the pulse button on the front panel. Note this is NOT the hardware trigger, as it is only executing the pulse command and not directly driving the MOSFET itself.
Parameters:state – (bool): True (firmware trigger mode) or False (arm mode)
Returns:The state of the emode.
faults_current

This will get the current faults that are on the system.

Returns (list):

This will return a list of dictionaries containing the list of faults. The list will be empty if none exist.

Parameters:

fault – (int): When 0 it will attempt to clear the faults. Clearing the faults is need in order to arm after a fault has occured during the arm period.

Types:
  • fault_probe - Probe connection is not connected properly.

  • fault_overtemp - One of the temperature sensors has gone over 80C

    Note: This will not recover until temperature goes below 70C.

  • fault_panel_open - The case is open.

  • fault_high_voltage - Measured high voltage disagrees with requested by too much.

  • fault_ram_crc - RAM corrution has occured.

  • fault_eeprom_crc - EEPROM corruption has occured.

  • fault_gpio_error - GPIO mismatch between a requested value and actual.

  • fault_charge - Charge circuit error, or 19V input out-of-range (including brown-out).

  • fault_trigger_error - Trigger occured while disarmed or external hardware trigger help active for too long (More than 10msec)

  • fault_hardware_exc - Hardware monitor detected unspecified hardware fault.

  • faults_trig_glitch - Trigger was attempted while device disarmed.

  • faults_overvoltage - Charge circuit error, over-voltage on HV output detected.

  • faults_temp_sensor - Temperature sensor has failed to read correctly for too long.

Example:
>>> cs = ChipSHOUTER('COM10')     # Connect to shouter
Serial Interface Started
Shouter API Started
>>> cs.state                      # Check the state of the shouter.
'disarmed'
>>> cs.armed = 1                  # Arm the shouter.
>>> cs.state
'armed'
>>> cs.state                      # Cause fault... and check state.
'fault'
>>> cs.faults_current             # List the faults.
['fault_probe']
>>> cs.faults_current = 0         # After fault fixed, Clear it.
>>> cs.state                      # Check the state
'disarmed'
>>> 
faults_latched

This will get the latched faults that had occured on the system. An example of needing the finding issues when a fault occured for a short period of time, and is cleared by the time you look at the current faults.

More information is documented with faults_current.

Returns (list):

This will return a list of dictionaries containing the list of faults. The list will be empty if none exist.

Example:
>>> cs = ChipSHOUTER('COM10')     # Connect to shouter
Serial Interface Started
Shouter API Started
>>> cs.state                      # Check the state of the shouter.
'disarmed'                        # I heard an error tone 
cs.faults_current                 # What was it???
[]                                # Funny nothing wrong here.
>>> cs.faults_latched             # Anything latched???
[{'fault': 1, 'name': 'trigger'}, {'fault': 1, 'name': 'trig_g'}]
>>>                               # Ahhhh... flakey trigger.
get_pat_length()[source]

This will get the length of the pattern wave programmed in the ChipSHOUTER firmware.

Returns:(int): The length of the programmed pattern wave in the ChipSHOUTER.
get_pat_wave()[source]

The wave used for the pattern trigger when pat_enable is ‘True’.

NOTE: You MUST end the pattern with an inactive value, which will depend on the setting of hwtrig_mode . Normally this means ensuring you end with a ‘0’ or ‘False’.

For example, setting a pattern of ‘11100011110000’:

Pattern  1 1 1 0 0 0 1 1 1 1 0 0 0 0 
         _ _ _       _ _ _ _        
Trigger |     |_ _ _|       |_ _ _ _

        ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^
        | | | | | | | | | | | | | | |
Time:   20  60  00  40  80  20  60  
 (nS)     40  80  20  60  00  40  80

See the ChipSHOUTER manual specifications for details of the maximum wave length and exact time-step size.

hwtrig_mode

Trigger Polarity (Active-high vs Active-low) Configure hardware trigger (SMB connector) as active high or active low. When configured as active low ensure the pin is externally driven high during operation to prevent false triggers.

This command switches the entire internal trigger logic. When switching hwtrig_mode and using the pattern trigger, you will need to invert the pattern trigger logic.

Parameters:value – (bool): True (active-high) or False (active-low) mode.
Returns (bool):State of the termination.
hwtrig_term

Hardware Trigger Input termination mode. Configure hardware trigger (SMB connector) as high impedance (‘False’) or 50-ohm (‘True’). The 50-Ohm impedance option puts a 50R resistor to ground. If you are not using the hardware trigger it is suggested to set this True, as it will reduce potential noise on the hardware trigger causing glitches.

Parameters:value – (bool): True (50-ohm) or False (approx 1.8K-ohm) impedance.
Returns (bool):State of the termination.
id

Read the board id. This board id is needed for firmware updates to get the encrypted/signed firmware file.

Returns (string):
 The string id of the ChipSHOUTER.
mute

Mute the audio output, preventing beeping and fault tones.

Parameters:state – (bool): True (mute = On, thus no noise) or False
pat_enable

Enable the pattern trigger, if not set to True then the basic trigger is used instead.

pat_wave

The wave used for the pattern trigger when pat_enable is ‘True’.

When reading the This will return the string up to 96 bits.

If the length is more than 96 bits the string will append ‘… ( 4904 more )’ >>> cs.pat_wave ‘11111111111111111111111111111111111111…111111111111111 … ( 4904 more )’ >>> NOTE: To get pattern waves that are longer than 96 use the get_pat_wave function.

example:
>>> cs.pat_wave = '11001'
>>> cs.pat_wave
'11001'
>>> cs.pat_wave = '1'*97
>>> cs.pat_wave
'111111111111111111111111111111111111111...11111111111111111 ... ( 1 more )'
>>> cs.get_pat_wave()
'111111111111111111111111111111111111111...11111111111111111'
>>>

NOTE: You MUST end the pattern with an inactive value, which will depend on the setting of hwtrig_mode . Normally this means ensuring you end with a ‘0’ or ‘False’.

For example, setting a pattern of 11100011110000:

Pattern  1 1 1 0 0 0 1 1 1 1 0 0 0 0 
         _ _ _       _ _ _ _        
Trigger |     |_ _ _|       |_ _ _ _

        ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^
        | | | | | | | | | | | | | | |
Time:   20  60  00  40  80  20  60  
 (nS)     40  80  20  60  00  40  80

See the ChipSHOUTER manual specifications for details of the maximum wave length and exact time-step size.

pulse

Sets parameters for the pulse generator and causes the pulse to be triggered.

Parameters:pulse – (bool): When set to True causes a pulse to occur.

The settings of the basic pulse generator is done as follows:

      _________________________________________ repeat (3)
     |                  |                  |
     v                  v                  v
   ____               ____               ____
__|    |_____________|    |_____________|    |____________
    ^       ^
    |        \__ Dead time
    |___ pulse width 
Member:

.deadtime: (int): - Time between pulses in mS

Member:

.repeat: (int): - Number of pulses per trigger, the trigger being the pulse command, the front-panel button, or the RJ12 firmware pulse pin when enabled.

Member:

.width: (int): - Basic pulse generator: Requested pulse width in nS, check the measured result to see actual possible setting.

Member:

.measured: (int): - Basic pulse generator: actual pulse width in nS.

Example:
>>> cs = ChipSHOUTER('COM10')     # Connect to shouter
>>> cs.pulse.width = 120 #120 nS pulse width
>>> cs.pulse.repeat = 5 #5 pulses
>>> cs.pulse.deadtime = 15 #15mS deadtime
>>> cs.pulse = 1 #Trigger a pulse
ready_for_commands(retries=3)[source]

ready_for_commands is a function to wait for the firmware to be ready to communicate

reset

Set to True causes a hardware reset.

reset_config

Set to ‘True’ resets all configuration values to default (pulse width etc).

run_console()[source]

Runs the serial interface console in text mode.

status()[source]

This will indicate the status of the connection to the ChipSHOUTER.

Returns:(bool): True if connected successfully. False if not.
temperature_diode

Read the temperature of the catch diode.

Returns (int):temperature
temperature_mosfet

Read the temperature of the MOSFET.

temperature_xformer

Read the temperature of the transformer.

Returns (int):temperature
trigger_safe

Informs the ChipShouter that it is safe to read sensors.

Typically, the ChipShouter will read a temperature sensors every few hundred ms. This can fail during a discharge event. Calling trigger_safe while the ChipShouter is armed will do an immediate sensor read, then disable temperature sensor reads. This must be called periodically, determined by absent_temp, to read the temperature sensor. If absent_temp elapses without a temperature read, the ChipShouter will fault.

This manual temperature read mode will be disabled upon disarming the scope.

Returns (bool):
  • The sensors have been read and trigger_safe is enabled
  • False if the system is not armed or in fault.
update_firmware(file)[source]

Updates the firmware of the connected ChipSHOUTER

Supports both .fup and .bin files. If a .fup file is used, will verify that the firmware and ChipSHOUTER board IDs match.

Args:
file (str): Path to the firmware file
voltage

Sets the voltage or reads the voltage

Parameters:

voltage – (int): The voltage level you wish to set. Note This is between 150 and 500 Volts

Returns:

This will return both members of the voltage: set and measured.

Member:

.set - This is the voltage that is targeted to be set.

returns:The set voltage
Member (Read only):
 

.measured - This is the actual voltage that is put out of the ChipSHOUTER.

returns:The measured voltage
Example:
>>> from chipshouter import ChipSHOUTER
>>> cs = ChipSHOUTER('COM10')
Serial Interface Started
Shouter API Started
>>> cs.voltage
set      = 200
measured = 209
>>> cs.voltage.set
200
>>> cs.voltage.measured
210
>>>
>>> cs.voltage = 300
>>> cs.voltage
set      = 300
measured = 298

This documentation is part of the ChipSHOUTER Python API.

Permission is hereby granted, free of charge, to any person obtaining a copy of this ChipSHOUTER Python API software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

ChipSHOUTER is a registered trademark of NewAE Technology Inc.

Indices and tables