Built-in I/O pins. More...
Core components | |
| PinMode | Mode [get, set] |
| Get or set the mode of the pin. More... | |
| string | Name [get, set] |
| Gets the name of the pin More... | |
| PropertyChangedEventHandler | PropertyChanged |
| This event fires whenever a property changes More... | |
Digital components | |
| bool | DigitalValue [get, set] |
| Gets or sets the digital value of the pin. More... | |
| OnDigitalInValueChanged | DigitalValueChanged |
| Occurs when the input on the pin changes. More... | |
| Task< bool > | AwaitDigitalValueChangeAsync () |
| Wait for the digital input value of the pin to change More... | |
| Task | ToggleOutputAsync () |
| Toggles the output value of the pin. More... | |
| async Task | WriteDigitalValueAsync (bool value) |
| Write a value to a pin More... | |
| Task | MakeDigitalInAsync () |
| Make the pin a digital input. More... | |
| Task | MakeDigitalPushPullOutAsync () |
| Make the pin a push-pull output. More... | |
| Task | MakeDigitalOpenDrainOutAsync () |
| Make the pin a push-pull output. More... | |
AnalogValue components | |
| double | AnalogValue [get] |
| Retrieve the last reading from the ADC, expressed on a unit range (0.0 - 1.0) More... | |
| double | AnalogValueChangedThreshold = 0.01 [get, set] |
| Gets or sets the value threshold required to fire the AnalogValueChanged event. More... | |
| OnAnalogValueChanged | AnalogValueChanged |
| Occurs when an analog value is changed, according to the set threshold. More... | |
| Task< double > | AwaitAnalogValueChangeAsync () |
| Wait for the pin's analog value to change. More... | |
AnalogVoltage components | |
| double | AnalogVoltage [get] |
| Retrieve the last voltage reading from the ADC. More... | |
| double | AnalogVoltageChangedThreshold = 0.05 [get, set] |
| Gets or sets the voltage threshold required to fire the AnalogVoltageChanged event. More... | |
| OnAnalogVoltageChanged | AnalogVoltageChanged |
| Occurs when an analog voltage is changed, according to the set threshold. More... | |
| Task< double > | AwaitAnalogVoltageChangeAsync () |
| Wait for the pin's analog voltage to change. More... | |
AdcValue components | |
| int | AdcValue [get] |
| Retrieve the last value obtained from the ADC. More... | |
| int | AdcValueChangedThreshold = 10 [get, set] |
| Gets or sets the value threshold required to fire the AdcValueChanged event. More... | |
| OnAdcValueChanged | AdcValueChanged |
| Occurs when the normalized analog value is changed, according to the set threshold. More... | |
| Task< int > | AwaitAdcValueChangeAsync () |
| Wait for the pin's ADC value to change. More... | |
Core analog components | |
| AdcReferenceLevel | ReferenceLevel [get, set] |
| Sets the ADC reference value used More... | |
| Task | MakeAnalogInAsync () |
| Make the pin an analog input. More... | |
SoftPWM components | |
| double | DutyCycle [get, set] |
| double | PulseWidth [get, set] |
| async Task | EnablePwmAsync () |
| Enable the PWM functionality More... | |
| async Task | DisablePwmAsync () |
| Disables the PWM functionality More... | |
Other components | |
| int | PinNumber [get, set] |
| The pin number of the pin. More... | |
| TreehopperUsb | Board [get] |
| This returns a reference to the Treehopper board this pin belongs to. More... | |
| Spi | SpiModule [get] |
| Gets the Spi module that can use this pin for chip-select duties More... | |
| override string | ToString () |
| Gets a string representation of the pin's current state More... | |
Detailed Description
Built-in I/O pins.
Quick guide
Once you have connected to a TreehopperUsb board, you can access pins through the Pins property of the board.
You can manipulate pins directly:
Or create reference variables:
You can choose whether a pin should be a digital input, digital output, analog input, or soft-PWM output by setting the pin's Mode property to one of the values in PinMode.
You can set or retrieve the digital value of a pin by accessing the DigitalValue property. Note that writing to this property — even if the pin is an input — will implicitly force it to be an output.
If the pin is set as an analog input, you can access its data through any of the following properties:
- AnalogValue: retrieve a normalized (0.0 - 1.0) pin value
- AnalogVoltage: retrieve the voltage (0.0 - 3.3) on the pin
- AdcValue: retrieve the raw ADC value (0 - 4095) of the pin
More information
This section dives into more details and electrical characteristics about Treehopper's pins.
Pin mode
You can choose whether a pin should be a digital input, output, or analog input by setting the pin's Mode property.
Digital outputs
All pins on Treehopper support both push-pull and open-drain outputs. Writing a true or false to the pin's digital value will flush that value to the pin.
- Push-Pull: Push-pull is the most commonly used output mode; when a pin is set to true, Treehopper will attempt to drive the pin to logic HIGH (3.3V) — when a pin is set to false, Treehopper will attempt to drive the pin to logic LOW (0V — ground).
- Open-Drain: Open-drain outputs can only drive a strong logic LOW (0V); in the HIGH state, the pin is weakly pulled high.
Output current limitations
Treehopper's output impedance varies, but is roughly 100 ohm source and 50 ohm sink when supplying weaker loads, but increases as the load increases. In the worst-case scenario (when short-circuited), Treehopper can source approximately 20 mA of current, and sink approximately 40 mA of current. The pin's drivers are rated for a maximum of 100 mA of output current, so you cannot damage the board by short-circuiting its output to ground or 3.3V.
While this is plenty of current for peripheral ICs and small indicator LEDs, do not expect to drive large arrays of LEDs, or low-impedance loads like motors, solenoids, or speakers directly from Treehopper's pins. There are a wide variety of peripherals in the Treehopper.Libraries package for your language API that can be used for interfacing with these peripherals.
- Warning
- To avoid damaging the device permanently, do not source or sink more than 400 mA of combined current out of the pins on the board! Note that these limits have nothing to do with the 3.3V supply pins found on Treehopper, which can comfortably source 500 mA — or the unfused 5V pin, which has no imposed current limit (other than that of your computer).
Digital input
Treehopper's digital inputs are used to sample digital signals — i.e., signals that have either a LOW or HIGH state. Logic LOW (false) is considered a voltage less than or equal to 0.6V. Logic HIGH (true) is considered a voltage greater than or equal to 2.7V.
Treehopper pins are true 5V-tolerant signals; consequently, you do not need any sort of logic-level conversion or series-limiting resistor when using the pin as a digital input with a 5V source.
You can access the most recent DigitalValue, or use the DigitalValueChanged event to subscribe to change notifications.
Analog inputs
Each Treehopper pin can be read using the on-board 12-bit ADC. There is no limit to the total number of analog pins activated at any time.
Output Format
When the pin is sampled and sent to the host, the value is simultaneously available to the user in three forms:
- AdcValue – the raw, 12-bit result from conversion.
- AnalogValue – the normalized value of the ADC (from 0-1).
- AnalogVoltage – the actual voltage at the pin (taking into account the reference level).
There are OnChanged events associated with each of these properties:
Plus thresholds for each of these events that give you fine-grained control over when the event will fire:
Reference Levels
Each pin has a configurable ReferenceLevel that can be used to measure the pin against. The possible reference levels are:
- 3.3V generated by the on-board LDO, rated at 1.5% accuracy (default).
- 3.7V (effective) reference derived from the on-chip 1.85V reference.
- 2.4V on-chip reference rated at 2.1% accuracy.
- 1.85V on-chip reference.
- 1.65V on-chip reference, 1.8% accurate.
- 3.3V (effective) reference that is derived from the on-chip 1.65V reference.
For most ratiometric applications — i.e., when measuring a device whose output is ratioed to its power supply — connect the sensor's power supply to the 3.3V supply pin the Treehopper and use the default 3.3V reference. The other reference options are provided for advanced scenarios that involve reading from precision voltage outputs accurately.
INotifyPropertyChanged
Pin implements INotifyPropertyChanged, and all the digital and analog value properties will also fire PropertyChanged messages.
As a result, you can directly bind GUI controls like progress bars, checkboxes, etc to Treehopper pins in WPF, UWP, or Xamarin.Forms applications, and they will automatically update.
A note about pin reads
All of Treehopper's pins configured as digital or analog inputs are sampled continuously onboard; when any pin changes, this data is sent to the host device. When you access the digital or one of the analog value properties, you're accessing the last received data. This makes property reads instantaneous — keeping your GUI or application running responsively.
For almost all applications, changes to digital or analog inputs are to be reacted to (like with switches, interrupt outputs, encoders), or sampled (like with sensor outputs). Care must be taken, however, if you need to synchronize pin reads with other functions.
For example, consider the case where you electrically short pins 0 and 1 together on the board, and then run this code:
A work around is to wait for two consecutive pin updates to be received before checking the pin's value. This can be accomplished by awaiting TreehopperUsb.AwaitPinUpdateAsync().
However, pin updates are only sent to the computer when a pin's value changes, so if you wish to synchronously sample a pin that might not change, you should set an unused pin as an analog input, which will almost certainly guarantee a constant stream of pin updates:
SoftPWM functionality
Each Treehopper pin can be used as a SoftPWM pin.
Performance Considerations
Writing values to (or changing pin modes of) Treehopper pins will flush to the OS's USB layer immediately, but there is no way of achieving guaranteed latency.
Occasional writes (say, on the order of every 20 ms or more) will usually flush to the port within a few hundred microseconds. If your application is chatty, or the bus you're operating on has other devices (especially isochronous devices like webcams), you may see long periods (a millisecond or more) of delay.
Analog pins take a relatively long time to sample; if you enable tons of analog inputs, the effective sampling rate will drop by up to two times.
Member Function Documentation
◆ AwaitDigitalValueChangeAsync()
| Task<bool> AwaitDigitalValueChangeAsync | ( | ) |
Wait for the digital input value of the pin to change
- Returns
- An awaitable bool, indicating the pin's state
Implements DigitalIn.
◆ ToggleOutputAsync()
| Task ToggleOutputAsync | ( | ) |
Toggles the output value of the pin.
Calling this function on a pin that is configured as an input will automatically make the pin an output before writing the value to it.
In this example, an LED attached to pin 4 is made to blink.
Implements DigitalOut.
◆ WriteDigitalValueAsync()
| async Task WriteDigitalValueAsync | ( | bool | value | ) |
Write a value to a pin
- Parameters
-
value The value to write
- Returns
- An awaitable task that completes upon success
This method is functionally equivalent of calling "<see cref="DigitalValue" />=value", however, it provides finer-grained control over asynchronous behavior. You may choose to await it, block it synchronously, or "forget" it (continue execution without waiting at all).
◆ MakeDigitalInAsync()
| Task MakeDigitalInAsync | ( | ) |
Make the pin a digital input.
Implements DigitalIn.
◆ MakeDigitalPushPullOutAsync()
| Task MakeDigitalPushPullOutAsync | ( | ) |
Make the pin a push-pull output.
Implements DigitalOut.
◆ MakeDigitalOpenDrainOutAsync()
| Task MakeDigitalOpenDrainOutAsync | ( | ) |
Make the pin a push-pull output.
◆ AwaitAnalogValueChangeAsync()
| Task<double> AwaitAnalogValueChangeAsync | ( | ) |
Wait for the pin's analog value to change.
- Returns
- An awaitable double of the analog value, normalized from 0-1.
◆ AwaitAnalogVoltageChangeAsync()
| Task<double> AwaitAnalogVoltageChangeAsync | ( | ) |
Wait for the pin's analog voltage to change.
- Returns
- An awaitable double of the pin's analog voltage, measured in volts.
◆ AwaitAdcValueChangeAsync()
| Task<int> AwaitAdcValueChangeAsync | ( | ) |
Wait for the pin's ADC value to change.
- Returns
- An awaitable int, in the range of 0-4095, of the pin's ADC value.
◆ MakeAnalogInAsync()
| Task MakeAnalogInAsync | ( | ) |
Make the pin an analog input.
Implements AdcPin.
◆ EnablePwmAsync()
| async Task EnablePwmAsync | ( | ) |
Enable the PWM functionality
///
- Returns
- An awaitable task that completes when the PWM functionality is enabled
Implements Pwm.
◆ DisablePwmAsync()
| async Task DisablePwmAsync | ( | ) |
Disables the PWM functionality
- Returns
- An awaitable task that completes when the PWM functionality is disabled
Implements Pwm.
◆ ToString()
| override string ToString | ( | ) |
Gets a string representation of the pin's current state
- Returns
- the pin's current state
Property Documentation
◆ Mode
|
getset |
Get or set the mode of the pin.
◆ Name
|
getset |
Gets the name of the pin
This is a useful property when binding pins in drop-down lists and other GUI controls. Pin names include the number and special function (if any) the pin has.
◆ DigitalValue
|
getset |
Gets or sets the digital value of the pin.
Setting a value to a pin that is configured as an input will automatically make the pin an output before writing the value to it.
The value retrieved from this pin will read as "0" when then pin is being used for other purposes.
◆ AnalogValue
|
get |
Retrieve the last reading from the ADC, expressed on a unit range (0.0 - 1.0)
◆ AnalogValueChangedThreshold
|
getset |
Gets or sets the value threshold required to fire the AnalogValueChanged event.
◆ AnalogVoltage
|
get |
Retrieve the last voltage reading from the ADC.
◆ AnalogVoltageChangedThreshold
|
getset |
Gets or sets the voltage threshold required to fire the AnalogVoltageChanged event.
◆ AdcValue
|
get |
Retrieve the last value obtained from the ADC.
Treehopper has a 12-bit ADC, so ADC values will range from 0-4095.
◆ AdcValueChangedThreshold
|
getset |
Gets or sets the value threshold required to fire the AdcValueChanged event.
◆ ReferenceLevel
|
getset |
Sets the ADC reference value used
◆ DutyCycle
|
getset |
◆ PulseWidth
|
getset |
◆ PinNumber
|
getset |
The pin number of the pin.
◆ Board
|
get |
This returns a reference to the Treehopper board this pin belongs to.
◆ SpiModule
|
get |
Gets the Spi module that can use this pin for chip-select duties
Since the SPI chip-select functionality is done in-hardware, the SPI module must check to ensure the pin you're using for chip-select actually belongs to the same board as the SPI module does (as you may have multiple boards attached).
Event Documentation
◆ PropertyChanged
| PropertyChangedEventHandler PropertyChanged |
This event fires whenever a property changes
◆ DigitalValueChanged
| OnDigitalInValueChanged DigitalValueChanged |
Occurs when the input on the pin changes.
This event will only fire when the pin is configured as a digital input.
◆ AnalogValueChanged
| OnAnalogValueChanged AnalogValueChanged |
Occurs when an analog value is changed, according to the set threshold.
The Changed event is raised when the 10-bit ADC value obtained is different from the previous reading by at least the value specified by AdcValueChangedThreshold
◆ AnalogVoltageChanged
| OnAnalogVoltageChanged AnalogVoltageChanged |
Occurs when an analog voltage is changed, according to the set threshold.
The Changed event is raised when the 12-bit ADC value obtained is different from the previous reading by at least the value specified by AnalogVoltageChangedThreshold.
◆ AdcValueChanged
| OnAdcValueChanged AdcValueChanged |
Occurs when the normalized analog value is changed, according to the set threshold.
The Changed event is raised when the 10-bit ADC value obtained is different from the previous reading.
The documentation for this class was generated from the following file:
- F:/Git/treehopper-sdk/NET/API/Treehopper/Pin.cs