digital.py

The digital functionality currently supported by the PiSoC Python API

Digital Input and Output

class digital.DigitalPin(port, pin, configuration=None)
Class:

Provides functionality for use of the GPIO on the PiSoC as a digital input or output, with a number of different drive mode configurations.

Example:

Define a DigitalPin object in the following way:

>>>My_input = DigitalPin(port,pin,'input')
>>>My_output = DigitalPin(port,pin,'output')

Note

Modification of which pins are available should be easy. Just add new pins to you PiSoC schematic, give them an input and an output, and then name them as GPIO_PORT_PIN. After you do this, confirm that it was done correctly by using the info qualifier when constructing the PiSoC class.


Method:

__init__

Description:

Constructs and initializes a DigitalPin object

Parameters:
  • port (int) – Port on the PiSoC
  • pin (int) – Pin relative to chosent port on the PiSoC.
  • configuration (str) –

    Drive mode of the pin

    input:Sets pin as an input (High Impedance)
    output:Sets pin as an output (Strong Drive)
    pull_up:Sets pin as an input with a resistive pullup. Pin will be driven high.
    pull_down:Sets pin as an input with a resistive pulldown. Pin will be driven low.
    open_drain_lo:Sets pin as open drain (drives low)
    open_drain_hi:Sets pin as open drain (drives high)
    pull_up_down:Sets pin as resitive pull up/down
Returns:

None

Note

GPIO pins unavailable to the firmware will raise a ValueError. Verify valid port and pin assignments using the info qualifier when PiSoC is constructed.

Configure(config)
Method:Configure
Parameters:config (str) –

Drive mode of the pin

input:Sets pin as an input (High Impedance)
output:Sets pin as an output (Strong Drive)
pull_up:Sets pin as an input with a resistive pullup. Pin will be driven high.
pull_down:Sets pin as an input with a resistive pulldown. Pin will be driven low.
open_drain_lo:Sets pin as open drain (drives low)
open_drain_hi:Sets pin as open drain (drives high)
pull_up_down:Sets pin as resitive pull up/down
Returns:None
Read(bitmap=None, port=False)
Method:

Read

Description:

Determines the state of the digital pin on the PiSoC

Parameters:
  • bitmap (int) – An optional input, which when provided will be used to decide the state of the pin instead of asking the PiSoC. It is a hexadecimal value which represents either the states of all pins, as returned by get_gpio_bitmap(), or the state of all pins on its port, as returned by get_port_state(). Providing a bitmap to this function simply abstracts the bit manipulation required to decode that result.
  • port (bool) – Specifies if the bitmap should represent a map of all gpio, or just a map of this pins port. If no bitmap is provided, this parameter does nothing.
Returns:

boolean value (True/False) which indicates the state of the DigitalPin as HIGH/LOW, respectively

Toggle()
Method:Toggle
Description:Toggles the state of the specified output
Returns:None
Write(val)
Method:Write
Description:Writes a new value to the DigitalPin
Parameters:val (int) – Value to be written. val should be 1 or 0 for writing the output HIGH or LOW, respectively.
Returns:None
get_gpio_bitmap()
Method:get_gpio_bitmap
Description:Calculates an n-bit integer between 0 and \(2^n - 1\) which represents the state of each available GPIO between 0 and n, where n is the number of GPIO available. The pins are sorted 0 - n according to their port and pin numbers. The lowest pin number on the lowest port number is equal to pin 0, and the highest pin number on the highest port number is equal to pin n. Use this when minimizing data transfers is desired.
Returns:an integer value between 0 and \(2^n - 1\) where n is the number of GPIO available. The binary representation of this number gives information on each pin state. The kth bit will give the state of the kth available pin. Bit 0 is the LSB and Bit n is the MSB. This result can be provided to the instance method Read() as a bitmap to abstract the calculation of True/False.
get_port_state()
Method:get_port_state
Description:Calculates an 8-bit value which represents the state of each pin on this pins associated port. Use this when minimizing data transfers is desired.
Returns:an integer value between 0 and 255. The binary representation of this number gives information on each pin state. The nth bit will give the state of the nth pin on this port. Bit 0 is the LSB and Bit 7 is the MSB. This result can be provided to the instance method Read() as a bitmap to abstract the calculation of True/False.

PWM

class digital.PWM(channel, frequency=None, duty_cycle=None)
Class:

This class provides functionality for use of the PWM components available on the PiSoC.

Example:

Define PWM objects in the following way:

>>> My_PWM = PWM(0)

Method:

__init__

Description:

Constructs and initializes PWM object

Parameters:
  • channel (int) – Corresponds to one of the physical PWM pins on your PiSoC, valid inputs are 0-7
  • frequency (float) – Optional parameter. If specified, the PWM will switch with this frequency in Hertz.
  • duty_cycle (float) – Optional parameter. If specified, the PWM will have this duty cycle. This value should represent the percentage of time during one PWM cycle that the output is HIGH. Valid values are 0-100
Returns:

None

ClearFIFO()
Method:ClearFIFO
Description:Clears the capture FIFO of any previously captured data. Here PWM_ReadCapture() is called until the FIFO is empty
Returns:None
GetClockDivider()
Method:GetClockDivider
Description:Gets the most recently confirmed clock divider value, which is used to determine the clocking frequency of the PWM
Returns:16-bit integer value representing the current clock divider mapped to the source clock for this PWM.
GetClocks(precision=2)
Method:GetClocks
Description:Calculates the actual clock rate of the PWM’s based on the most recently confirmed clock divider value
Parameters:precision (int) – Optional parameter. Specifies how many decimal places the result should be calculated to.
Returns:Floating point value which represents the source clock frequency for this PWM in Hertz.
GetDutyCycle(precision=2)
Method:GetDutyCycle
Description:Calculates the current duty cycle based on the current period and comparison values
Parameters:precision (int) – Optional parameter. The number of decimal places which the result should be calculated to. Defaults to 2.
Returns:A floating point value which is representative of the percentage of time, between 0 and 100%, that the PWM signal is on, relative to the total length of its period
GetFrequency(precision=2)
Method:GetFrequency
Description:Calculates the current PWM wave frequency based on the current clock rate and period value
Parameters:precision (int) – Optional parameter. The number of decimal places which the result should be calculated to. Defaults to 2.
Returns:A floating point value, which is representative of the current PWM signal frequency in Hz
GetMIDI()
Method:GetMIDI
Description:Calculates what MIDI note corresponds to the current PWM frequency
Returns:The integer MIDI note, as defined by the MIDI standard to correspond with a specific musical note, which most closely resembles the PWM frequency
ReadCompare()
Method:ReadCompare
Description:Determines the comparison value, in counts, currently set by the PWM component
Returns:Integer value representing the count value at which the PWM signal will change states during any given cycle, relative to the period.
Example:If the period is set to 100, and the comparison value is set to 20, the PWM signal will be HIGH for 20% of its period, and then LOW for the remaining 80%
ReadPeriod()
Method:ReadPeriod
Description:Determines the period value, in counts, currently set by the PWM component
Returns:Integer value representing the PWM period in counts
SetClockDivider(divider)
Method:SetClockDivider
Description:Sets a clock divider to be mapped to the desired PWM’s clock source
Parameters:divider (int) – An integer between 0 and 65535 which the PWM clock will be divided by
Returns:None

Warning

Changing the clock’s divider, and consequently its frequency, will affect any other PWMs which share that clock

SetClocks(frequency)
Method:SetClocks
Description:Attempts to set the PWM Clock rate to a desired frequency using an appropriate clock divider.
Parameters:frequency (float) –

A frequency in Hz which represents the desired clock rate

  • This is NOT the frequency of the PWM, it is the frequency of the clock which drives it
  • Changing the clock frequency for any single PWM that shares it’s clock source will affect all PWMs that share this clock
  • For the suggested clock source of 24 MHz, this value cannot be less than 367 Hz and cannot be more than 24 MHz (24000000 Hz)
  • Generally, the frequency cannot be less than your clock source divided by 65535, and cannot be greater than your clock source itself
Returns:None

Warning

Because frequencies are calculated with dividers, high frequencies result in greater potential deviation.
  • For a 24 MHz source, frequencies higher than 2.526 MHz accuracy cannot be guaranteed to be within a tolerance of 5%
  • For a 24 MHz source, frequencies higher than 5.333 MHz accuracy cannot be guaranteed to be within a tolerance of 10%
  • The frequency might still be accurate at high frequencies; tolerances are worst case scenarios
  • Use GetClocks() to get the actually achieved frequency
SetDutyCycle(duty_cycle)
Method:SetDutyCycle
Description:Simplifies the process of setting a meaningful comparison value by calculating it based on a desired duty cycle then setting it to the PWM hardware.
Parameters:duty_cycle (float) –

value between 0 and 100 which indicates the percentage of time that the PWM should be HIGH during one period

  • A duty_cycle of 100 indicates that the PWM is always on
  • A duty_cycle of 50 indicates that the PWM is on half of the time
  • A duty_cycle of 0 indicates that the PWM is always off
Returns:None
SetFrequency(freq, max_error=5, min_period=10)
Method:

SetFrequency

Description:

Attempts to set the PWM wave frequency to a desired rate by calculating an appropriate period value and/or clock rate. It will try to maintain the clock rate, unless it is impossible without compromising the duty cycle too severely, in which case a warning will be issued.

Parameters:
  • freq (float) –

    A frequency in Hz which represents the desired wave rate

    • This is NOT the frequency of the clock which drives the PWM, it is the actual output frequency of the PWM signal
    • If the frequency cannot be reached without changing the clock rate, any PWM’s sharing that clock will be affected
    • For the suggested source clock rate of 24MHz, freq cannot be less than .006 Hz and cannot be more than 2.4 MHz (2400000 Hz)
    • Generally, freq cannot be less than \(\frac{clock freq}{65535*(2^n - 1)}\), where n is the PWM resolution in bits, and it cannot be more than \(\frac{clock freq}{min\_period}\)
  • max_error (float) –

    Optional parameter. The largest percentage of error that can be tolerated between the desired frequency and the achieved frequency

  • min_period (int) –

    Optional parameter. The lowest possible period that can be tolerated when the wave parameters are being calculated

    • Valid between 0 and 65535 for a 16-bit PWM
    • Valid between 0 and 255 for an 8-bit PWM
    • Default behavior is a min_period of 10 on 16-bit PWM
    • Lower values allow for easier wave parameter calculation, without having to modify the clock source
    • Higher values allow finer Duty Cycle maintenence
Returns:

None

SetMIDI(midi, max_error=5, min_period=10)
Method:

SetMIDI

Description:

Generates a PWM wave frequency the corresponds to the specified midi note

Parameters:
  • midi (int) – A midi note, as defined by the midi standard to correspond with a specific musical note
  • max_error (float) –

    Optional parameter. The largest percentage of error that can be tolerated between the desired frequency and the achieved frequency

    • This defaults to 5
    • This error rate is in reference to the wave frquency, in Hz, not the midi note number which is scaled differently than the frequency
  • min_period (int) –

    Optional parameter. The lowest possible period that can be tolerated when the wave parameters are being calculated

    • Valid between 0 and 65535 for a 16-bit PWM
    • Valid between 0 and 255 for an 8-bit PWM
    • Default behavior is a min_period of 10 on 16-bit PWM
    • Lower values allow for easier wave parameter calculation, without having to modify the clock source
    • Higher values allow finer Duty Cycle maintenence
Returns:

None

Sleep()
Method:Sleep
Description:Stops the PWM operation, puts the PWM component into it’s lowest power state, and saves the current configuration
Returns:None
Start()
Method:Start
Description:Starts component operation. Sets the initVar variable, calls the PWM_Init function, and then calls the PWM_Enable function
Returns:None
Stop()
Method:Stop
Description:Disables component operation
Returns:None
Wakeup()
Method:Wakeup
Description:Restores and enables the most recently saved configuration
Returns:None
WriteCompare(cmp)
Method:WriteCompare
Description:Writes the comparison value used by the PWM hardware to determine the point in the PWM cycle at which the state will change, relative to the period.
Parameters:cmp (int) – The length, in counts, which defines the switching point relative to the PWM period * The value must not be greater than 65535 (for 16-bit mode, which is the default) * for 8-bit mode it must not be greater than 255 * The comparison value must be less than or equal to the period
Returns:None
WritePeriod(period)
Method:WritePeriod
Description:Writes the period value used by the PWM hardware
Parameters:period (int) –

The length, in counts, which defines how long a PWM Cycle will be

  • The value must not be greater than 65535 (for 16-bit mode, which is the default)
  • for 8-bit mode it must not be greater than 255
  • The period must be greater than the comparison value
Returns:None
is_running()
Method:is_running
Description:Checks if the PWM component is currently operational
Returns:boolean result which evaluates to True if the PWM component is operational, or False if it is not

Servo Motors

class digital.Servo(channel, min_pulse=1.0, max_pulse=2.0, min_angle=0, max_angle=180)
Class:

This class provides tools for easy manipulation of standard Servo Motors using PWM.

Example:

Define Servo objects in any the following ways:

>>> My_simple_servo       = Servo(0)
>>> My_calibrated_servo   = Servo(1, min_pulse = 1.0, max_pulse = 2.0)
>>> My_descriptive_servo  = Servo(7, min_pulse = 1.0, max_pulse = 2.0, min_angle = 0, max_angle = 180)

Method:
Description:

Creates a servo object with the given parameter set

Parameters:
  • channel (int) – Corresponds to the pin which the signal line of the servo will be connected to. Uses the same numbering convention as PWM
  • min_pulse (float) –

    Optional parameter. The pulse width (in milliseconds) necessary to obtain angular position min_angle.

    • Values must be greater than zero
    • Normal values are between 0.8 and 1.2
    • Find an appropriate value through calibration; it will default to 1.0 if no parameter is given
  • max_pulse (float) –

    Optional parameter. The pulse width (in milliseconds) necessary to obtain angular position max_angle.

    • Values must be greater than zero
    • Normal values are between 1.8 and 2.3
    • Find an appropriate value through calibration; it will default to 2.0 if no parameter is given
  • min_angle (float) –

    Optional parameter. The angle which the servo will return to if applied with a pulse width of min_pulse.

    • This defaults to 0
    • Negative angular positions are valid
    • Angles can be any angular unit: degrees, radians, or other arbitrary (linear) scale
  • max_angle (float) –

    Optional parameter. The angle which the servo will return to if applied with a pulse width of max_pulse.

    • This defaults to 180
    • Negative angular positions are valid
    • Angles can be any angular unit: degrees, radians, or other arbitrary (linear) scale
Returns:

None

Note

A servo with channel n, will make PWM(n) unnavailable, since the servo controller is implemented using that PWM object. For fine control over that PWM, you can expose the internal use of the PWM instance using My_servo.servo_PWM, and then you can use any of the PWM methods using My_servo.servo_PWM.method(). This is advised against though, because servos are very particular about the construction of their data signals. If you change the wrong parameter of the PWM signal, you might damage the motor.

ChangeAngles(min_angle, max_angle)
Method:

ChangeAngles

Description:

Changes the angle range that defines the minimum and maximum positions of the motor

Parameters:
  • min_angle (float) –

    Optional parameter. The angle which the servo will return to if applied with a pulse width of min_pulse.

    • This defaults to 0
    • Negative angular positions are valid
    • Angles can be any angular unit: degrees, radians, or other arbitrary (linear) scale
  • max_angle (float) –

    Optional parameter. The angle which the servo will return to if applied with a pulse width of max_pulse.

    • This defaults to 180
    • Negative angular positions are valid
    • Angles can be any angular unit: degrees, radians, or other arbitrary (linear) scale
Returns:

None

ReadAngle()
Method:ReadAngle
Description:Calculates the current angle of the servomotor, linearized relative to the provided maximum and minimum angles
Returns:A value representative of the angle that the servo motor is held, according to the scale set within the class.
ReadPulse()
Method:ReadPulse
Description:Calculates the current pulse width of the PWM which is driving the servomotor
Returns:A pulse duration in milliseconds which characterizes the state of the PWM signal being applied to the servomotor
SetAngle(angle)
Method:SetAngle
Description:Calculates a pulse width based on the given angular position and the current min/max configuration parameters, then calls SetPulse() to set the position of the servo
Parameters:angle (float) – The angle to which the servo should be set, linearized relative to the defined minimum and maximum angles
Returns:None
SetPulse(pulse_ms)
Method:SetPulse
Description:Sets a servo position based on a pulse width in ms
Parameters:pulse_ms (float) – A pulse width in milliseconds, which will be applied to the signal wire of the Servo at 50 Hz. Normal values are between 0.8 and 2.3, but they must be between the defined min_pulse and max_pulse values
Returns:None
Start()
Method:Start
Description:Starts component operation.
Returns:None
Stop()
Method:Stop
Description:Stops the servo object by terminating the PWM channel that drives it
Returns:None

Note

This may cause the servo to move slightly out of position

is_running()
Method:is_running
Description:Checks to see if the Servo component is currently operational
Returns:A boolean variable which evaluates to True if the PWM component is operational, or False if it is not

Musical Tones

class digital.Tone(channel)
Class:

The Tone class provides an easy way to integrate musical tones into your programs by setting Notes or frequencies which can be played through a piezo buzzer.

Example:

Define a Tone object in any the following way:

>>> Note = Tone(0)
Method:

__init__

Description:

Constructs and initializes the Tone object.

Parameters:

channel (int) – Corresponds to the output pin of the Tone signal. Uses the same numbering convention as PWM

Returns:

None

GetFrequency(precision=2)
Method:GetFrequency
Description:Calculates the current Tone frequency based on known parameters of it’s driving PWM
Parameters:precision (int) – Optional parameter. The number of decimal places which the result should be calculated to. Defaults to 2.
Returns:None
GetMIDI()
Method:GetMIDI
Description:Calculates what MIDI note corresponds to the current Tone frequency
Returns:The Midi note, as defined by the Midi standard to correspond with a specific musical note
GetVelocity()
Method:GetVelocity
Description:Calculates the volume of the Tone and adjusts it to be consistent with the MIDI velocity standard
Returns:The integer Tone velocity between 0 and 127, as defined by the Midi standard.
GetVolume(max_volume=10)
Method:GetVolume
Description:Calculates the current volume
Parameters:max_volume (int) – Optional parameter. Scales the volume result according to a scale of 0 to max_volume. Default is 10.
Returns:Integer value reprsenting the current volume between 0 and max_volume
SetFrequency(freq, max_error=5)
Method:

SetFrequency

Description:

Attempts to set the Tone frequency to a desired rate by calculating an appropriate period value and/or clock rate for it’s driving PWM

Parameters:
  • freq (float) –

    A frequency in Hz which represents the desired wave rate

    • If the frequency cannot be reached without changing the clock rate, any Tone objects sharing that clock will be affected
    • For the suggested source clock rate of 24MHz, freq cannot be less than .006 Hz and cannot be more than 2.4 MHz (2400000 Hz)
    • Generally, freq cannot be less than \(\frac{clock freq}{65535*(2^n - 1)}\), where n is the PWM resolution in bits, and it cannot be more than \(\frac{clock freq}{MIN PERIOD}\)
  • max_error (float) –

    The largest percentage of error that can be tolerated between the desired frequency and the achieved frequency

Returns:

None

SetMIDI(note, max_error=5)
Method:

SetMIDI

Description:

Generates a Tone frequency which corresponds to the specified MIDI note

Parameters:
  • note (int) – An integer Midi note, as defined by the Midi standard to correspond with a specific musical note
  • max_error (float) –

    Optional parameter. The largest percentage of error that can be tolerated between the desired frequency and the achieved frequency.

    • This defaults to 5
    • This error rate is in reference to the wave frquency, in Hz, not the MIDI note number which is scaled differently than the frequency
Returns:

None

SetNote(note, octave, max_error=5)
Method:

SetNote

Description:

Sets the Tone frequency to that of a desired musical note

Parameters:
  • note (str) –

    The desired letter note

    • Valid parameters are ‘A’, ‘A#’, ‘B’, ‘B#’, ‘C’, ‘C#’, ‘D’, ‘D#’, ‘E’, ‘E#’, ‘F’, ‘F#’, ‘G’, ‘G#’
  • octave (int) – The desired musical octave in which to play the note. Valid input between 0 and 9.
  • max_error (float) –

    Optional parameter. The largest percentage of error that can be tolerated between the desired frequency and the achieved frequency.

    • This defaults to 5
    • This error rate is in reference to the wave frquency, in Hz, not the MIDI note number which is scaled differently than the frequency
Returns:

None

SetVelocity(velocity)
Method:SetVelocity
Description:Adjusts the volume of the note to correspond with the MIDI velocity standard
Parameters:velocity (int) – The desired velocity. Valid input is between 0 and 127, as defined by the MIDI standard
Returns:None
SetVolume(volume, max_volume=10, log_base=2)
Method:

SetVolume

Description:

Adjusts the volume of the note logarithmically according to the provided scale.

Parameters:
  • volume (float) – The desired volume between 0 and max_volume
  • max_volume (float) – Optional parameter. The maximum volume level which will define the volume scale. Defaults to 10.
  • log_base (int) – Optional parameter. The base of the logarithmic growth used to fit the volume growth to a logarithmic scale. A higher base will result in less drastic volume adjustments in the lower range of the scale, and more drastic ones towards the higher end. This can result in a more linear sounding volume adjustment, due to the logarithmic nature of human hearing.
Returns:

None

Sleep()
Method:Sleep
Description:Stops the Tone operation, puts the driving PWM component into it’s lowest power state, and saves the current configuration
Returns:None
Start()
Method:Start
Description:Starts component operation.
Returns:None
Stop()
Method:Stop
Description:Stops the tone by terminating the PWM channel that drives it
Returns:None
Wakeup()
Method:Wakeup
Description:Restores and enables the most recently saved Tone configuration
Returns:None
is_running()
Method:is_running
Description:Checks to see if the Tone’s PWM component is currently operational
Returns:None

NeoPixels

class digital.NeoPixelShield
Class:

This class provides functionality for use of an Arduino NeoPixels shield on an PiSoC through Python.

Example:

Create a NeoPixelShield object in the following way:

>>> shield = NeoPixelShield()
Method:

__init__

Description:

Defines the register address for the striplight controller used by the NeoPixels, and it defines 140 colors as class attributes, named according to their standardized HTML and CSS names

Returns:

None

Clear()
Method:Clear
Description:Clears the entire display.
Returns:None
ClearColumn(column)
Method:ClearColumn
Description:Clears all pixels within a specified row
Parameters:column (int) – Column which contains the desired pixel to be set. Valid entries are 0-7.
Returns:None
ClearPixel(row, column)
Method:

ClearPixel

Description:

Clears the given pixel at location (x,y) = (row, column)

Parameters:
  • row (int) – Row which contains the desired pixel to be set. Valid entries are 0-4.
  • column (int) – Column which contains the desired pixel to be set. Valid entries are 0-7.
Returns:

None

ClearRow(row)
Method:ClearRow
Description:Clears all pixels within the specified row.
Parameters:row (int) – Row which contains the desired pixel to be set. Valid entries are 0-4.
Returns:None
DrawColumn(column, color)
Method:

DrawColumn

Description:

Sets the pixels in a specified column to a desired color.

Parameters:
  • column (int) – Column which contains the desired pixel to be set. Valid entries are 0-7.
  • color (int) –

    A 24-bit number representative of a BRG value

    • BRG components are given equal weight, so 8-bits each
    • There are predefined colors inside of __init__(), which can be called as shield.[color name]; example: shield.Blue
Returns:

None

DrawRow(row, color)
Method:

DrawRow

Description:

Sets the pixels in a specified row to a desired color.

Parameters:
  • row (int) – Row which contains the desired pixel to be set. Valid entries are 0-4.
  • color (int) –

    A 24-bit number representative of a BRG value

    • BRG components are given equal weight, so 8-bits each
    • There are predefined colors inside of __init__(), which can be called as shield.[color name]; example: shield.Blue
Returns:

None

Fill(color)
Method:Fill
Description:Fills the entire display with a specified color.
Parameters:color (int) –

A 24-bit number representative of a BRG value

  • BRG components are given equal weight, so 8-bits each
  • There are predefined colors inside of __init__(), which can be called as shield.[color name]; example: shield.Blue
Returns:None
RGB_to_hex(RGB)
Method:RGB_to_hex
Description:Converts RGB content to the needed BRG Hex value taken by the NeoPixelShield device
Parameters:RGB (list) –

A list or tuple containing three elements, each of which is limited to one byte (0-255)

  • The first element is the Red byte
  • The second element is the Green byte
  • The thirf element is the Blue byte
Returns:A hex value which can be used as a valid color input for SetPixel(), DrawRow(), DrawColumn(), Fill(), and Stripe().

Example Usage:

>>> from pisoc import *
>>> shield = NeoPixelShield()
>>> shield.Start()
>>> shield.SetBrightness(3)
>>> purple = shield.RGB_to_hex([255, 0, 255]) #purple = Full Red, No Green, Full Blue
>>> shield.Fill(purple)
SetBrightness(brightness)
Method:SetBrightness
Description:Preserves the color of each pixel already drawn or to be drawn to the shield, but adjusts the brightness.
Parameters:brightness (int) – Integer value in the range of 0 - 5. A value of 0 will clear the display, and a value of 5 indicates maximum brigthness.
Returns:None
SetPixel(row, column, color)
Method:

SetPixel

Description:

Sets the given pixel at location (x,y) = (row, column), to a color defined by a 24 bit Blue-Red-Green (BRG) value (8-bits each)

Parameters:
  • row (int) – Row which contains the desired pixel to be set. Valid entries are 0-4.
  • column (int) – Column which contains the desired pixel to be set. Valid entries are 0-7.
  • color (int) –

    A 24-bit number representative of a BRG value

    • BRG components are given equal weight, so 8-bits each
    • There are predefined colors inside of __init__(), which can be called as shield.[color name]; example: shield.Blue
Returns:

None

Start()
Method:Start
Description:Powers up and enables the needed hardware for the NeoPixels component
Returns:None
Stop()
Method:Stop
Description:Powers down and disables the needed hardware for the NeoPixels component
Returns:None
Stripe(pixelnum, color)
Method:

Stripe

Description:

Draws a line of specified length in a desired color, starting from the first pixel, and extending as far as the 40th (last) pixel. It will wrap around rows if required.

Parameters:
  • pixelnum (int) – Indicates how many pixels, starting with pixel (0,0), will be filled. Valid input between 1 and 40
  • color (int) –

    A 24-bit number representative of a BRG value

    • BRG components are given equal weight, so 8-bits each
    • There are predefined colors inside of __init__(), which can be called as shield.*color_name*; example: shield.Blue
Returns:

None

is_running()
Method:is_running
Description:Checks to see if the NeoPixels display is currently powered up
Returns:A boolean variable which evaluates to True if the NeoPixels display is running, or False if it is not

Ultrasonic Range Finding

class digital.RangeFinder(signal, trigger=None, delay_us=10, timeout_us=30000, poll_frequency=None)
Class:

This class provides functionality for use of ultrasonic range finder devices that use standard GPIO pulse width sonic time-of-flight measurement protocols

Example:
Define a RangeFinder object in the following way::
>>> #set signal pin to 12[0], trigger pin to 12[1], and specify a maximum poll frequency of 50Hz.
>>> my_ranger = RangeFinder([12,0], trigger = [12, 1], poll_frequency = 50) 

Method:

__init__

Description:

Initializes an object by describing which pin the echo will be measured on. Optionally, provide a trigger pin if the ranger is a 4 or 5 pin form factor. Also optionally provide a trigger pulse width and timeout value in milliseconds, or a maximum frequency in Hz.

Parameters:
  • signal (list) – A list constructed as [port, pin] which defines which exact pin will be used to communicate with the rangers signal/echo pin
  • trigger (list) –

    A list constructed as [port, pin] which defines which exact pin will be used to communicate with the rangers trigger pin

    • By default, if no argument is provided, it will assume the trigger pin is the same as the echo pin; this is true for 3-pin devices and so no argument is needed
  • delay_us (int) – Optional Parameter. Integer value representing the width of the trigger pulse, in microseconds, that will be sent from the TRIGGER pin to signal the ranger to send a ping. Defaults to 10.
  • timeout_us (int) –

    The maximum length of time, in microseconds, that the PiSoC will wait for a confirmed echo

    • If this time is exceeded, the ranger will immediately terminate its current process and return the timeout as a response
    • This defaults as 30000 microseconds, which is equivalent to 30 ms, and is much longer than generally needed and so won’t usually need to be altered
    • Refer to your devices documentation for a more specific timeout choice
  • poll_frequency (float) – Optional parameter. When set, this API will not make calls to the range finder more frequently than specified. A call to read from the RangeFinder will block and wait until the specified time has passed so that another call can be made. Valid entries are in Hertz. Range Finding modules often should not be polled more frequently than 50Hz, and so setting that as a maximum will prevent invalid responses. If a call is attempted too quickly, note that use of this parameter will cause that call to block and delay execution of the rest of your program.
Returns:

None

ReadCentimeters(sound=343.0, precision=2)
Method:

ReadCentimeters

Description:

Uses ReadMeters() and then converts the result to centimeters.

Parameters:
  • sound (float) –

    Optional parameter. The speed of sound which is used to calcuate the distance of the object detected by the ranger

    • Defaults to 343 m/s (approximate value based on room temperature of air)
    • Must be m/s
    • Modify this according to your environmental needs (different temperature/medium)
  • precision (int) – Optional parameter. The number of decimal places which the result should be calculated to. Defaults to 2.
Returns:

The distance, in centimeters, between the ultrasonic ranger and the pinged object

ReadInches(sound=343.0, precision=2)
Method:

ReadInches

Description:

Uses ReadCentimeters() and then converts the result to inches

Parameters:
  • sound (float) –

    Optional parameter. The speed of sound which is used to calcuate the distance of the object detected by the ranger

    • Defaults to 343 m/s (approximate value based on room temperature of air)
    • Must be m/s
    • Modify this according to your environmental needs (different temperature/medium)
  • precision (int) – Optional parameter. The number of decimal places which the result should be calculated to. Defaults to 2.
Returns:

The distance, in inches, between the ultrasonic ranger and the pinged object

ReadMeters(sound=343.0, precision=2)
Method:

ReadMeters

Description:

Uses ReadRaw() to get a raw time value in microseconds, and then calculates the distance between the ranger and the pinged object in meters

Parameters:
  • sound (float) –

    Optional parameter. The speed of sound which is used to calcuate the distance of the object detected by the ranger

    • Defaults to 343 m/s (approximate value based on room temperature of air)
    • Must be m/s
    • Modify this according to your environmental needs (different temperature/medium)
  • precision (int) – Optional parameter. The number of decimal places which the result should be calculated to. Defaults to 2.
Returns:

The distance, in meters, between the ultrasonic ranger and the pinged object

ReadRaw()
Method:ReadRaw
Description:Gets a raw value from the PiSoC, which is representative of how many microseconds the rangers echo pin was held high
Returns:The length of time, in microseconds, that it took for the ping to echo back to the ultrasonic ranger.
SetDelay(delay_us)
Method:SetDelay
Description:Sets the length of the trigger pulse, in microseconds, which will be used to tell the device to send out a ping
Parameters:delay_us (int) – Amount of time, in microseconds, that the PiSoC will hold its trigger pulse high. This is a 6 bit value, and so it must be between 0 and 63
Returns:None

Note

This is handled in __init__(), and so this value should be set in the class constructor. This method should only be called under unique circumstances.

SetTimeout(timeout_us)
Method:SetTimeout
Description:Sets the timeout length in microseconds. If the PiSoC is still waiting for a completed response after this amount of time, it will terminate its current process immediately return the result
Parameters:timeout_us (int) – Amount of time, in microseconds, that the PiSoC will wait for a completed response. Valid inputs are between 1 and 65535.
Returns:None

Note

This is handled in __init__(), and so this value should be set in the class constructor. This method should only be called under unique circumstances.

Table Of Contents

Previous topic

API modules

Next topic

analog.py

This Page