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
- This defaults to 5
- Verify the actual frequency with GetFrequency()
- 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
- freq (float) –
- 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
- min_angle (float) –
- 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
- This defaults to 5
- Verify the actual frequency with GetFrequency()
Returns: None
- freq (float) –
- 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
- note (str) –
- 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: 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
- sound (float) –
- 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
- sound (float) –
- 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
- sound (float) –
- 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.
