# analog.py¶

The analog functionality currently supported by the PiSoC API

class analog.AnalogPin(pin)
Class: Provides functionality for use of the general purpose analog input pins exposed on the PiSoC Define an AnalogPin object in the following way: >>> My_analog_pin = AnalogPin(pin) 

Method: __init__ Constructs and initializes an AnalogPin object for general purpose analog input pin (int) – The analog pin number - This directly corresponds to the pins connected to your sequenced SAR ADC, where 0 is the top pin V2.0 of the PiSoC firmware has 10 analog pins available, and so valid arguments are 0-9. The default version assigns Port 3 pins 0-7 as AnalogPins 0-7, respectively. pin 8 and 9 are on P0[4] and P0[5], respectively. None
Method: Read Reads the calculated digital value after analog to digital conversion Digital value after an A/D conversion The size of this value and the voltage which is represented by it will depend on the resolution set (or not set) by SetResolution() Default resolution is 12 (SetResolution() never called), so $$Voltage = 5.0*\frac{counts}{2^{12} - 1}$$ int
Method: ReadVolts Reads the specified analog pin and converts that digital reading to a voltage in Volts, or converts a given count value to Volts if one is provided precision (int) – Optional parameter. The number of decimal points to be included in the returned result. Defaults to 2. counts (int) – Optional parameter. If given, the provided count value will be converted to a voltage according to $$Voltage = 5.0*\frac{counts - offset}{2^{n} - 1}$$, where n is the ADC resolution in bits and offset is optionally set with SetOffset() (defaults to 0 otherwise) A floating point number representative of an analog voltage taken with respect to PiSoC ground.
SetOffset(counts)
Method: SetOffset Sets an offset on the ADC which is used for the voltage conversion. It will subtract the given offset before making the conversion counts (int) – Digital value which will be subtracted from any digital result before its conversion to a voltage takes place None
SetResolution(resolution)
Method: SetResolution This function sets the resolution of ALL AnalogPin objects. The resolution is defaulted to 12, so this method is only needed if this needs to be changed resolution (int) – An integer value, in bits, that represents the new resolution of the SAR ADC. Valid arguments are 8, 10, and 12 None

## Capacitive Sensing (CapSense)¶

class analog.CapSense(pin, threshold=6)
Class: Provides functionality for use of CapSense buttons on the PiSoC Define a CapSense object in the following way: >>> button = CapSense(0) 

Method: __init__ Initializes a Capsense object for use as a touch sensor pin (int) – The capsense pin number. pin n directly corresponds to the pin which is assigned to Capsense_BTN_N in the pisoc firmware V2.0 of the firmware uses 8 CapSense buttons, so valid arguments are 0 - 7 pins 0-6 exist on Port 4 pins 0-6, respectively. pin 7 exists on P0[6] threshold (int) – Optional parameter. The number of counts, between 0 and 255, that any touch reading must exceed above the calculated baseline for a touch to be processed. By default this value is 6. This tends to be sufficient for most use cases. If the sensor used is hard to characterize, a higher threshold may be needed for fewer errors. A lower threshold can give some proximity detection None

Note

threshold is only needed for is_touched() (the suggested reading method). Read() is only valid when SmartSense is enabled in firmware, which by default it is not.

Method: Read Determines the state of the capsense button, as determined by PSoC SmartSensing. This will need to be calibrated in PSoC Creator for optimal results. Use is_touched() for more general application A boolean (True or False) value when the output is determined to be touched or not touched, respectively.

Warning

This functionality has been deprecated since version 1.2 because the implementation was slow. It will only work if the firmware will support it. It has since been replaced by is_touched() but it is maintained as a seperate function for legacy purposes.

Method: ReadRaw Gives an 8-bit raw value from the capsense raw data array, which represents capacitance detection and is thus correlated with touch data. Use this to calibrate touch buttons by deciding an approriate threshold as described in __init__() The raw value on the capsense button, which can be used to characterize the nature of a touch event
Sleep()
Method: Sleep Prepares the component for the device entering a low-power mode. Disables Active mode power template bits of the sub components used within CapSense, saves nonretention registers, and resets all sensors to an inactive state. None

Warning

This will affect functionality of all CapSense sensors, use it only if this is intended.

Start()
Method: Start Initializes registers and enables active mode power template bits of the subcomponents used within CapSense. Also establishes a CapSense baseline, which is used as a comparison value in is_touched() None

Note

If the sensor is touched when this method is called, the sensor will be calibrated to a touched value. This may or may not be desireable based on application.

Stop()
Method: Stop Disables component interrupts, and calls CapSense_ClearSensors() to reset all sensors to an inactive state None

Warning

This will affect functionality of all CapSense sensors, use it only if this is intended.

Wakeup()
Method: Wakeup Restores CapSense configuration and nonretention register values after the device wake from a low power mode sleep mode None

Warning

This will affect functionality of all CapSense sensors, use it only if this is intended.

get_register()
Method: get_register Calculates a touched event for all enabled CapSense sensors, and returns the result as a single 8-bit hexadecimal value containing the state of each sensor. 8-bit hexadceimal value where the binary representation contains the state information for each pin. The n-th bit of this value will be 1 if pin n is touched, or 0 if pin n is not touched. Bit-0 is the LSB of the returned result.
is_running()
Method: is_running Checks to see if the CapSense component and all subcomponents are currently operational A boolean variable which evaluates to True if CapSense is active, or False if it is not
is_touched(bitmap=None)
Method: is_touched Uses the calibrated baseline and provided threshold value to determine if the requested CapSense button is being touched. This is the suggested method for touch detection. bitmap (int) – An optional input, which when provided will be used to decide if the sensor has been touched instead of asking the PiSoC. It is a hexadecimal value which represents the state of all capsense sensors, as returned by get_register(). Providing a bitmap to this function simply abstracts the bit manipulation required to decode that result. A boolean (True or False) value when the output is determined to be touched or not touched, respectively

Class: The ADC class provides functionality for using the Delta Sigma ADC and two Succesive Approximation ADC’s on the PiSoC. Define ADC objects in the following way: >>> My_DELSIG = ADC('DELSIG') >>> My_SAR = ADC('SAR0') >>> My_other_SAR = ADC('SAR1') 

Method: __init__ Constructs and initializes an ADC object for use of a SAR or DELSIG ADC c_type (str) – Specifies the type of ADC to be used. Valid arguments are: ‘DELSIG’- This is for the Delta sigma ADC, which has resolution up to 20 bits, but a slower conversion rate ‘SAR0’ or ‘SAR1’ - These are for the as many as two Successive Approximation ADCs, which has resolution of 8, 10, or 12 bits, but with a very fast conversion rate None
CountsTo_Volts(counts)
Method: CountsTo_Volts Converts the ADC output to a Voltage, taking into account any set gains or offsets counts (int) – Digital value to be converted to it’s analog equivalent (voltage in Volts) Floating point value representative of converted voltage
GetResult()
Method: GetResult Gets the result of a conversion which has been completed. StartConvert() must be called prior to this function, and StopConvert() must be called after Digital value which represents the result of the most recent AD conversion
IsEndConversion()
Method: IsEndConversion Checks to see if the ADC is done converting Boolean value (True/False) that will evaluate True if the most recent conversion is complete, otherwise False.
Method: Read Simplifies the reading process by starting conversion, waiting for conversion to complete, stopping conversion, and returing the result, when called. Digital value which represents the result of the most recent AD conversion
SetBufferGain(gain)
Method: SetBufferGain Sets the input buffer gain gain (int) – The number by which the ADC output will be multiplied after conversion . Valid arguments are 1, 2, 4, or 8 None

Note

Increasing the gain will lower the buffer bandwidth. This method is only available for the Delta-Sigma ADC; use with a SAR ADC will raise a ValueError

SetGain(gain)
Method: SetGain Sets the ADC gain in counts per volt, which will be applied before voltage conversion gain (int) – Output gain in counts per volt to be applied before conversion. None

Warning

gain is set by default by the reference and input range settings. It should only be used to further calibrate the ADC with a known input or if an external reference is used

SetOffset(offset)
Method: SetOffset Sets an offset on the ADC which is used for the voltage conversion. It will subtract the given offset before making the conversion offset (int) – Digital value which will be subtracted from any digital result before its conversion to a voltage takes place None
SetResolution(resolution)
Method: SetResolution This function sets the resolution of the SAR ADCs only. This method is unavailable for the DELSIG ADC. The resolution is defaulted to 12, so this method is only needed if this needs to be changed resolution (int) – An integer value, in bits, that represents the new resolution of the SAR ADC. Valid arguments are 8, 10, or 12 only None

Note

The ADC resolution cannot be changed during a conversion cycle. The recommended bestpractice is to stop conversions with Stop() before changing the resolution, and then restarting with Start() If you call SetResolution() during a conversion, the resolution will not change until the current conversion is complete, and data will not be available in the new resolution for another 6+resolution clock cycles

Sleep()
Method: Sleep Checks to see if the component is enabled, then it stops the ADC and saves the current configuration for later use None
Start()
Method: Start Sets the initVar variable on the PiSoC, calls the ADC_Init() function, and then calls the ADC_Enable() function. This function configures and powers up the ADC, but does not start conversions None
StartConvert()
Method: StartConvert Forces the ADC to initialize a conversion. This is handled internally for the Delsig ADC, using the Read() function, but it is kept seperate for the SAR. However, It can also be used for the Delsig None
Stop()
Method: Stop Disables and powers down the ADC None
StopConvert()
Method: StopConvert Forces the ADC to end conversion. This is handled internally for the Delsig ADC, using the Read() function, but it is kept seperate for the SAR. However, It can also be used for the Delsig None
Wakeup()
Method: Wakeup Restores and enables the most recently saved configuration of the ADC None
is_running()
Method: is_running Checks to see if the ADC component and all subcomponents are currently operational A boolean variable which evaluates to True if the ADC is active, or False if it is not

## Analog Output¶

Use these to generate analog voltages, currents, or waveforms.

### Voltage DAC (VDAC)¶

class analog.VDAC(channel)
Class: The VDAC class provides functionality for using the VDAC’s available on the PiSoC. Define VDAC objects in the following way: >>> My_VDAC = VDAC(0) >>> My_other_VDAC = VDAC(1)  __init__ Constructs and initializes a VDAC object channel – Determines which VDAC is to be utilized. 0 for the first VDAC, output is on P0[1]. Second VDAC not available by default. None
SetRange(mode)
Method:SetRange
Description:Sets the full scale range for the VDAC
Parameters:mode (int) –

Choices are 0 or 1

0: Sets full scale range to 4.080 V Sets full scale range to 1.020 V
Returns:None
SetSpeed(speed)
Method: SetSpeed Sets the DAC speed, and consequently the power level speed (str) – HIGH or LOW for high speed or low speed, respectively None
SetValue(value)
Method: SetValue Sets a digital value to be converted into an analog voltage and output by the VDAC value (int) – Value between 0 and 255 A value of 0 will correspond to an output of the lowest possible voltage output A value of 255 will output the full scale value, as selected with SetRange() All values between 0 and 255 are linearized according to the full scale range None
SetVoltage(volts)
Method: SetVoltage Sets a voltage in Volts to be output on the specified VDAC volts (float) – A number between 0 and the full scale range, as selected by SetRange(). This will be converted to an analog voltage and output. None
Sleep()
Method: Sleep Checks to see if the component is enabled, then it stops the VDAC and saves the current configuration for later use None
Start()
Method: Start Enables and powers up the VDAC None
Stop()
Method: Stop Powers down VDAC to lowest power state and disables output None
Wakeup()
Method: Wakeup Restores and enables the most recently saved configuration of the VDAC None
is_running()
Method: is_running Checks to see if the DAC component and all subcomponents are currently operational A boolean variable which evaluates to True if the DAC is active, or False if it is not

### Current DAC (IDAC)¶

class analog.IDAC(channel)
Class: The IDAC class provides functionality for using the IDAC’s available on the PiSoC. Define IDAC objects in the following way: >>> My_IDAC = IDAC(0) >>> My_other_IDAC = IDAC(1) 

Method: __init__ Constructs and initializes an IDAC object channel (int) – Determines which IDAC is to be utilized. V2.0 only exposes channel 0 by default - output on P0[7] None
SetCurrent(m_amps)
Method: SetCurrent Sets a current in milliamps to be output on the specified IDAC m_amps (float) – A number between 0 and the full scale range (in milliamps), as selected by SetRange(). This will be converted to an analog current and output from the IDAC. None
SetPolarity(polarity)
Method: SetPolarity Sets the DAC output polarity polarity (str) – String argument which should be SOURCE or SINK None
SetRange(mode)
Method:SetRange
Description:Sets the full scale range for the IDAC
Parameters:mode (int) –

Choices are 0, 1, and 2

0: Sets full scale range to 31.875 uA Sets full scale range to 255 uA Sets full scale range to 2.04 mA
Returns:None
SetSpeed(speed)
Method: SetSpeed Sets the DAC speed, and consequently the power level speed (str) – HIGH or LOW for high speed or low speed, respectively None
SetValue(value)
Method: SetValue Sets a digital value to be converted into an analog current and output by the IDAC value (int) – Value between 0 and 255 A value of 0 will correspond to an output of the lowest possible current output A value of 255 will output the full scale value, as selected with SetRange() All values between 0 and 255 are linearized according to the full scale range None
Sleep()
Method: Sleep Checks to see if the component is enabled, then it stops the DAC and saves the current configuration for later use None
Start()
Method: Start Sets the initVar variable on the PiSoC, calls the IDAC8_Init() function and then calls the IDAC8_Enable() function. Enables and powers up the IDAC None
Stop()
Method: Stop Powers down IDAC to lowest power state and disables output None
Wakeup()
Method: Wakeup Restores and enables the most recently saved configuration of the DAC None
is_running()
Method: is_running Checks to see if the DAC component and all subcomponents are currently operational A boolean variable which evaluates to True if the DAC is active, or False if it is not

### Wave DAC¶

class analog.WaveDAC
Class: The WaveDAC class provides functionality for using the WaveDAC available on the PiSoC. Define WaveDAC objects in the following way: >>> My_Wave = WaveDAC()  __init__ Constructs and initializes an WaveDAC object None
GenerateWave(waveType, amplitude=4.0, dc_bias=0.0)
Method: Provides functionality for generating a specific waveform Provides functionality for generating a specific waveform waveType (str) – The output behavior of the WaveDAC, Valid choices are: SINE, SQUARE, TRIANGLE, or SAWTOOTH amplitude (float) – Determines how the output waveform is scaled. Output will be such that this value is the maximum, with everything else being linearly related. dc_bias (float) – A voltage that will be added to each value (DC portion). If this causes values to exceed 255, they will clip at 4V. None
GetFrequency()
Method: GetFrequency Calculates the actual wave frequency based on the most recently confirmed clock divider value (float) The actual frequency of the wave, not a requested frequency
SetFrequency(frequency)
Method: SetFrequency Sets an approximate frequency by using an appropriate clock divider so that the resulting wave is as close to the desired frequency as possible frequency (float) – A frequency in Hz that will be representative of the output wave rate (Valid range is between 0.46 and 2500) None
SetSpeed(speed)
Method: SetSpeed Dets the DAC speed to one of the defined settings speed (str) – HIGH or LOW for high speed or low speed, respectively None
SetValue(val)
Method: SetValue Sets a digital value to be converted into a voltage and output by the WaveDAC. val (int) – Value between 0 and 255 None
Sleep()
Method: Sleep Checks to see if the component is enabled, then it stops the DAC and saves the current configuration for later use None
Start()
Method: Start Performs all of the required initialization for the component and enables power to the block None
StartClock()
Method: StartClock Restarts the WaveDAC clock after it has been stopped None
Stop()
Method: Stop Powers down the WaveDAC to its lowest power state and disables output None
StopClock()
Method: StopClock Stops the WaveDAC clock so that a value can be set without interference by the clock None
Wakeup()
Method: Wakeup Restores and enables the most recently saved configuration of the DAC None
is_running()
Method: is_running Checks to see if the DAC component and all subcomponents are currently operational A boolean variable which evaluates to True if the DAC is active, or False if it is not