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:
- configure settings:
- Capacitor bank voltage
- Pulse widths, settings (if using internal pulse generator)
- arm the device using:
- front-panel button, or
- sending arm command, or
- external IO pin on RJ12
- Triggering the pulse using:
- the pulse front-panel button, or
- the pulse command, or
- external IO pin on RJ12, or
- 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).
-
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, comport=None)[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 comport (str): Optional if using function stand-alone, specify comport
-
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.