analog.py

The analog functionality currently supported by the PiSoC API

Analog Input Pins

class analog.AnalogPin(pin)

Class:

Provides functionality for use of the general purpose analog input pins exposed on the PiSoC

Example:

Define an AnalogPin object in the following way:

>>> My_analog_pin = AnalogPin(pin)

Method:__init__ Description:Constructs and initializes an AnalogPin object for general purpose analog input Parameters: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.

Returns:None

Read()

Method:Read Description:Reads the calculated digital value after analog to digital conversion Returns: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}\)

Return type:int

ReadVolts(precision=2, counts=None)

Method:

ReadVolts

Description:

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

Parameters:

• 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)

Returns:

A floating point number representative of an analog voltage taken with respect to PiSoC ground.

SetOffset(counts)

Method:SetOffset Description:Sets an offset on the ADC which is used for the voltage conversion. It will subtract the given offset before making the conversion Parameters:counts (int) – Digital value which will be subtracted from any digital result before its conversion to a voltage takes place Returns:None

SetResolution(resolution)

Method:SetResolution Description: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 Parameters:resolution (int) – An integer value, in bits, that represents the new resolution of the SAR ADC. Valid arguments are 8, 10, and 12 Returns:None

Capacitive Sensing (CapSense)

class analog.CapSense(pin, threshold=6)

Class:

Provides functionality for use of CapSense buttons on the PiSoC

Example:

Define a CapSense object in the following way:

>>> button = CapSense(0)

Method:

__init__

Description:

Initializes a Capsense object for use as a touch sensor

Parameters:

• 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

Returns:

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.

Read()

Method:Read Description: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 Returns: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.

ReadRaw()

Method:ReadRaw Description: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__() Returns:The raw value on the capsense button, which can be used to characterize the nature of a touch event

Sleep()

Method:Sleep Description: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. Returns:None

Warning

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

Start()

Method:Start Description: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() Returns: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 Description:Disables component interrupts, and calls CapSense_ClearSensors() to reset all sensors to an inactive state Returns:None

Warning

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

Wakeup()

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

Warning

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

get_register()

Method:get_register Description: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. Returns: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 Description:Checks to see if the CapSense component and all subcomponents are currently operational Returns:A boolean variable which evaluates to True if CapSense is active, or False if it is not

is_touched(bitmap=None)

Method:is_touched Description: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. Parameters: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. Returns:A boolean (True or False) value when the output is determined to be touched or not touched, respectively

ADCs (advanced)

Use these for fine control of your analog input. For general analog input needs, analogPin is almost always sufficient

class analog.ADC(c_type)

Class:

The ADC class provides functionality for using the Delta Sigma ADC and two Succesive Approximation ADC’s on the PiSoC.

Example:

Define ADC objects in the following way:

>>> My_DELSIG    = ADC('DELSIG')
>>> My_SAR       = ADC('SAR0')
>>> My_other_SAR = ADC('SAR1')

Method:__init__ Description:Constructs and initializes an ADC object for use of a SAR or DELSIG ADC Parameters: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

Returns:None

CountsTo_Volts(counts)

Method:CountsTo_Volts Description:Converts the ADC output to a Voltage, taking into account any set gains or offsets Parameters:counts (int) – Digital value to be converted to it’s analog equivalent (voltage in Volts) Returns:Floating point value representative of converted voltage

GetResult()

Method:GetResult Description:Gets the result of a conversion which has been completed. StartConvert() must be called prior to this function, and StopConvert() must be called after Returns:Digital value which represents the result of the most recent AD conversion

IsEndConversion()

Method:IsEndConversion Description:Checks to see if the ADC is done converting Returns:Boolean value (True/False) that will evaluate True if the most recent conversion is complete, otherwise False.

Read()

Method:Read Description:Simplifies the reading process by starting conversion, waiting for conversion to complete, stopping conversion, and returing the result, when called. Returns:Digital value which represents the result of the most recent AD conversion

SetBufferGain(gain)

Method:SetBufferGain Description:Sets the input buffer gain Parameters:gain (int) – The number by which the ADC output will be multiplied after conversion . Valid arguments are 1, 2, 4, or 8 Returns: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 Description:Sets the ADC gain in counts per volt, which will be applied before voltage conversion Parameters:gain (int) – Output gain in counts per volt to be applied before conversion. Returns: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 Description:Sets an offset on the ADC which is used for the voltage conversion. It will subtract the given offset before making the conversion Parameters:offset (int) – Digital value which will be subtracted from any digital result before its conversion to a voltage takes place Returns:None

SetResolution(resolution)

Method:SetResolution Description: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 Parameters:resolution (int) – An integer value, in bits, that represents the new resolution of the SAR ADC. Valid arguments are 8, 10, or 12 only Returns: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 Description:Checks to see if the component is enabled, then it stops the ADC and saves the current configuration for later use Returns:None

Start()

Method:Start Description: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 Returns:None

StartConvert()

Method:StartConvert Description: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 Returns:None

Stop()

Method:Stop Description:Disables and powers down the ADC Returns:None

StopConvert()

Method:StopConvert Description: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 Returns:None

Wakeup()

Method:Wakeup Description:Restores and enables the most recently saved configuration of the ADC Returns:None

is_running()

Method:is_running Description:Checks to see if the ADC component and all subcomponents are currently operational Returns: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.

Example:

Define VDAC objects in the following way:

>>> My_VDAC       = VDAC(0)
>>> My_other_VDAC = VDAC(1)

Method:

__init__

Description:

Constructs and initializes a VDAC object

Parameters:

channel – Determines which VDAC is to be utilized. 0 for the first VDAC, output is on P0[1]. Second VDAC not available by default.

Returns:

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 1:Sets full scale range to 1.020 V

Returns:None

SetSpeed(speed)

Method:SetSpeed Description:Sets the DAC speed, and consequently the power level Parameters:speed (str) – HIGH or LOW for high speed or low speed, respectively Returns:None

SetValue(value)

Method:SetValue Description:Sets a digital value to be converted into an analog voltage and output by the VDAC Parameters: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

Returns:None

SetVoltage(volts)

Method:SetVoltage Description:Sets a voltage in Volts to be output on the specified VDAC Parameters: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. Returns:None

Sleep()

Method:Sleep Description:Checks to see if the component is enabled, then it stops the VDAC and saves the current configuration for later use Returns:None

Start()

Method:Start Description:Enables and powers up the VDAC Returns:None

Stop()

Method:Stop Description:Powers down VDAC to lowest power state and disables output Returns:None

Wakeup()

Method:Wakeup Description:Restores and enables the most recently saved configuration of the VDAC Returns:None

is_running()

Method:is_running Description:Checks to see if the DAC component and all subcomponents are currently operational Returns: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.

Example:

Define IDAC objects in the following way:

>>> My_IDAC       = IDAC(0)
>>> My_other_IDAC = IDAC(1)

Method:__init__ Description:Constructs and initializes an IDAC object Parameters:channel (int) – Determines which IDAC is to be utilized. V2.0 only exposes channel 0 by default - output on P0[7] Returns:None

SetCurrent(m_amps)

Method:SetCurrent Description:Sets a current in milliamps to be output on the specified IDAC Parameters: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. Returns:None

SetPolarity(polarity)

Method:SetPolarity Description:Sets the DAC output polarity Parameters:polarity (str) – String argument which should be SOURCE or SINK Returns: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 1:Sets full scale range to 255 uA 2:Sets full scale range to 2.04 mA

Returns:None

SetSpeed(speed)

Method:SetSpeed Description:Sets the DAC speed, and consequently the power level Parameters:speed (str) – HIGH or LOW for high speed or low speed, respectively Returns:None

SetValue(value)

Method:SetValue Description:Sets a digital value to be converted into an analog current and output by the IDAC Parameters: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

Returns:None

Sleep()

Method:Sleep Description:Checks to see if the component is enabled, then it stops the DAC and saves the current configuration for later use Returns:None

Start()

Method:Start Description: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 Returns:None

Stop()

Method:Stop Description:Powers down IDAC to lowest power state and disables output Returns:None

Wakeup()

Method:Wakeup Description:Restores and enables the most recently saved configuration of the DAC Returns:None

is_running()

Method:is_running Description:Checks to see if the DAC component and all subcomponents are currently operational Returns: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.

Example:

Define WaveDAC objects in the following way:

>>> My_Wave = WaveDAC()

Method:

__init__

Description:

Constructs and initializes an WaveDAC object

Returns:

None

GenerateWave(waveType, amplitude=4.0, dc_bias=0.0)

Method:

Provides functionality for generating a specific waveform

Description:

Provides functionality for generating a specific waveform

Parameters:

• 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.

Returns:

None

GetFrequency()

Method:GetFrequency Description:Calculates the actual wave frequency based on the most recently confirmed clock divider value Returns:(float) The actual frequency of the wave, not a requested frequency

SetFrequency(frequency)

Method:SetFrequency Description:Sets an approximate frequency by using an appropriate clock divider so that the resulting wave is as close to the desired frequency as possible Parameters:frequency (float) – A frequency in Hz that will be representative of the output wave rate (Valid range is between 0.46 and 2500) Returns:None

SetSpeed(speed)

Method:SetSpeed Description:Dets the DAC speed to one of the defined settings Parameters:speed (str) – HIGH or LOW for high speed or low speed, respectively Returns:None

SetValue(val)

Method:SetValue Description:Sets a digital value to be converted into a voltage and output by the WaveDAC. Parameters:val (int) – Value between 0 and 255 Returns:None

Sleep()

Method:Sleep Description:Checks to see if the component is enabled, then it stops the DAC and saves the current configuration for later use Returns:None

Start()

Method:Start Description:Performs all of the required initialization for the component and enables power to the block Returns:None

StartClock()

Method:StartClock Description:Restarts the WaveDAC clock after it has been stopped Returns:None

Stop()

Method:Stop Description:Powers down the WaveDAC to its lowest power state and disables output Returns:None

StopClock()

Method:StopClock Description:Stops the WaveDAC clock so that a value can be set without interference by the clock Returns:None

Wakeup()

Method:Wakeup Description:Restores and enables the most recently saved configuration of the DAC Returns:None

is_running()

Method:is_running Description:Checks to see if the DAC component and all subcomponents are currently operational Returns:A boolean variable which evaluates to True if the DAC is active, or False if it is not