User Tools


Link to this comparison view

2.0:peripherals [2015/09/16 02:00] (current)
Line 1: Line 1:
 +====== Peripherals ======
 +Peripheral commands and variables enable access to general purpose IOs (GPIOs), analog functions such as analog-digital converters (ADCs) and PWMs (Pulse Width Modulators). In the case of the ACKme Wahoo evaluation board, peripherals include the tri-color LED, the speaker, user buttons and the thermistor ADC. 
 +
 +Note that **peripheral** is used here in sense of an input or output device attached to the TruConnect device. This is not to be confused with a Bluetooth peripheral. ​
 +  ​
 +===== GPIOs =====  ​
 +
 +GPIO commands allow control of the function and direction of the GPIOs.
 +  * [[.variables#​gp_u|get gp u]] - List GPIO usage, direction and initialization.
 +  * [[.commands#​gfu|gfu]] - Configure GPIO function ​
 +  * [[.commands#​gdi|gdi]] - Set GPIO direction, for a GPIO functioning as ''​stdio''​ (Standard Input/​Output)
 +  * [[.commands#​gdis|gdis]] - Set ''​stdio''​ function and direction for multiple GPIOs  ​
 +  * [[.commands#​gge|gge]] - Get GPIO value, for a GPIO functioning as ''​stdio''​
 +  * [[.commands#​gges|gges]] - Get multiple values for GPIOs functioning as ''​stdio''  ​
 +  * [[.commands#​gge|gse]] - Set GPIO value, for a GPIO functioning as ''​stdio''​
 +  * [[.commands#​gges|gses]] - Set multiple values for GPIOs functioning as ''​stdio''​
 +
 +Typically, particular GPIOs are hard-wired to components such as LEDs, the speaker, and buttons. Other GPIOs are configurable for input and output. ​
 +
 +GPIOs can be used for special system functions, including (but not limited to):
 +  * enabling a speaker for the [[commands#​beep]] command
 +  * assigning a LED as a BLE connection indicator
 +  * selecting between serial bus modes: COMMAND or STREAM
 +  * pulse width modulator function
 +  * blink on BLE activity
 +  * general standard IO function
 +
 +==== GPIO Functions and Pins ====
 +
 +The table below shows functions, defaults and pins for the Bobcat GPIOs. ​
 +
 +In the following examples, the Wahoo evaluation board is used to demonstrate GPIO functions. The table also shows defaults, connections and header pins for the AMS001-E01.2 Wahoo. ​
 +^Bobcat ​  ​AMS001,​ AMS002 ​             ^^^^^Wahoo ​  ​AMS001-E01.2 ​                         ^^^ 
 +^GPIO   ​^Default ​         ^ADC^PWM^Pin^Default ​      ​^Connections ​              ​^Header Pin^        ​
 +|GPIO0 ​ |Reserved \\ for future use as i2c_sda, spi_mosi ​ |   ​| ​  | 4 |Reserved ​      | Do not connect |H1-1      |
 +|GPIO1 ​ |Reserved \\ for future use as i2c_scl, spi_clk ​  ​| ​  ​| ​  | 5 |Reserved ​      | Do not connect |H1-2      |
 +|GPIO2 ​ |user_tx ​         |ADC|   | 6 |user_tx ​      ​| ​                         |H1-3      |
 +|GPIO3 ​ |none             ​|ADC| ​  | 7 |none          |                          |H1-4      |
 +|GPIO4 ​ |none             ​| ​  ​| ​  | 9 |none          |                          |H1-5      |
 +|GPIO5 ​ |user_rx ​         |   ​| ​  | 10|user_rx ​      ​| ​                         |H1-6      |
 +|GPIO6 ​ |none, factory ​   |   ​| ​  | 11|none, factory |Button 1, factory reset   ​|H1-7 ​     |
 +|GPIO7 ​ |Reserved ​        ​| ​  ​| ​  | 12|Reserved ​     |Do not connect ​           |H1-8      |
 +|GPIO8 ​ |none             ​| ​  ​| ​  | 13|none ​         |                          |H2-7      |
 +|GPIO9 ​ |none             ​| ​  ​| ​  | 14|mode_sel ​     |Button 2, bus mode, wake  |H2-6      |
 +|GPIO10 |none             ​|ADC|PWM| 15|status_led ​   |Blue tri-color LED        |H2-5      |
 +|GPIO11 |none             ​|ADC|PWM| 16|none ​         |Green tri-color LED       ​|H2-4 ​     |
 +|GPIO12 |none             ​|ADC| ​  | 17|none ​         |Thermistor ​               |H2-3      |
 +|GPIO13 |none             ​|ADC|PWM| 18|speaker ​      ​|Speaker ​                  ​|H2-2 ​     |
 +|GPIO14 |none             ​|ADC|PWM| 20|stream_gpio ​  |Red tri-color LED         ​|H2-1 ​     |
 +
 +==== Viewing GPIO Usage ====
 +
 +To see the current GPIO usage, read the [[variables#​gp u|GPIO usage]] variable. The default Wahoo GPIO usage is:
 +<​code>​
 +> get gp u
 +!  # Description
 +#  0 i2c_sda
 +#  1 i2c_scl
 +#  2 user_tx
 +#  3 none
 +#  4 none
 +#  5 user_rx
 +#  6 none,​factory
 +#  7 reserved
 +#  8 none
 +#  9 mode_sel
 +# 10 status_led
 +# 11 none
 +# 12 none
 +# 13 speaker
 +# 14 stream_gpio
 +</​code>​
 +
 +**Note**: The ''​user_rts''​ and ''​user_cts''​ functions automatically override any other function configured on GPIO2 & GPIO3 when UART flow control is enabled using the [[variables#​ua f|ua f]] variable. The UART flow control functions cannot be set manually using the [[commands#​gfu|gfu]] command.
 +
 +==== Setting GPIO Function ====
 +
 +Use the [[commands#​gfu|GPIO function]] command to set a single GPIO to a specific function. ​
 +
 +After using [[commands#​gfu]],​ it may be necessary to save then reboot depending on the alternate function (some functions are only configured at boot up). 
 +
 +Use [[commands#​gdis]] command to set ''​stdio''​ function and direction for multiple GPIOs. See [[#​setting_and_getting_multiple_stdio_gpio_values|Setting and Getting Multiple STDIO GPIO Values]] below.
 +
 +Available functions are listed in the [[commands#​gfu|gfu]] command documentation. ​
 +
 +The [[commands#​gfu]] command fails if the GPIO is already configured for an alternate function. Disable the alternate function first by using ''​gfu <​GPIO#>​ none''​. ​
 +
 +For example, to disable the beep command and allow the Wahoo speaker GPIO to operate as ''​stdio'':​
 +
 +<​code>​
 +> gfu 13 none
 +Success
 +> gfu 13 stdio
 +Success
 +</​code>​
 +After these commands, ''​get gp u''​ lists GPIO 13 as stdio and the [[commands#​beep]] command fails:
 +<​code>​
 +> get gp u
 +!  # Description
 +...
 +# 13 stdio,hiz
 +...
 +beep 100
 +Command failed
 +</​code>​
 +
 +To use the Wahoo red LED to indicate when stream mode is on:
 +<​code>​
 +> gfu 14 none
 +Success
 +> gfu 14 stream_gpio
 +Success
 +> save
 +Success
 +> reboot
 +</​code>​
 +
 +Press Button 2 to toggle between command mode and stream mode. The Wahoo red LED comes on for stream mode. The Wahoo green LED may also be on or blinking, as it defaults to the ''​status_led''​ function. ​
 +
 +==== Setting and Getting a Single STDIO GPIO Value ====
 +
 +To set and get the value of a single GPIO, use the [[commands#​gse|gse]] and [[commands#​gge|gge]] commands.
 +
 +Note that to set a GPIO, the GPIO must have ''​stdio''​ function and the output direction. To get the value, the GPIO must have ''​stdio''​ function. See [[#​setting_gpio_function|Setting GPIO Function]]. ​
 +
 +For example:
 +<​code>​
 +> gdi 12 olo
 +Success
 +> gge 12
 +0
 +> gse 12 1
 +Success
 +> gge 12
 +1
 +</​code> ​
 +
 +==== Setting and Getting Multiple STDIO GPIO Values ====
 +
 +To set and get multiple ''​stdio''​ GPIO values, use the [[commands#​gses]] and [[commands#​gges]] commands. ​
 +
 +For example, for the Wahoo evaluation board, set GPIO 6 (Button 1) and GPIO 8 (Button 2) as ''​stdio''​ pull-down inputs, and GPIO 10 (green LED), GPIO 11 (blue LED) and GPIO 14 (red LED) as ''​stdio''​ outputs. ​
 +<​code>​
 +> gdis 666666166133663
 +Success
 +</​code>​
 +With no buttons pressed, get the values of the ''​stdio''​ GPIOs:
 +<​code>​
 +> gges
 +XXXXXX0XX000XX0
 +</​code>​
 +Now turn the red LED on:
 +<​code>​
 +> gses XXXXXXXXXX00XX1
 +Success
 +</​code>​
 +Press both buttons and get the values of the ''​stdio''​ GPIOs:
 +<​code>​
 +> gges
 +XXXXXX1XX100XX1
 +</​code>​
 +===== ADCs =====
 +
 +To read the value from an ADC, use the [[commands#​adc|adc]] command. For example, to read the Wahoo thermistor ADC value:
 +<​code>​
 +> adc 12
 +1655
 +</​code>​
 +The value reported is in mV. 
 +
 +The ADC mV reading accuracy currently available is +/-10%. A future version of TruConnect will provide a calibration facility to improve accuracy to +/​-3%. ​
 + 
 +To determine temperature from the Wahoo thermistor ADC, see [[.resources:​wahoothermistortable|Wahoo Thermistor Temperature vs ADC Value table]].  ​
 +
 +The ADC value can be read regardless of the GPIO function setting.
 + 
 +===== PWMs =====
 +
 +The [[.commands#​pwm|pwm command]] provides control of the frequency and duty cycle of a pulse width modulator output. PWMs are associated with specific GPIOs. The lowest possible frequency is about 128Hz, and the highest is 65536Hz. ​
 +
 +The GPIO must be set to the ''​pwm''​ function. See [[commands#​gfu]]. ​
 +
 +PWMs can be used for controlling the user LED and the speaker.
 +
 +===== LEDs =====
 +
 +The level of a LED can be controlled via a GPIO, with either the ''​stdio''​ or ''​pwm''​ function. ​
 +
 +The example below uses the Wahoo tri-color user LED. This contains a red, green and blue LED, which can be combined to form a wide range of colors: ​
 +
 +^Wahoo GPIO ^LED Color  ^
 +|14       | Red     |
 +|10       | Green   |
 +|11       | Blue    |
 +
 +These same GPIOs are associated with the Wahoo system indicator LEDs, if fitted. ​
 +
 +<!-- %%pageBreakAfter%% --> ​
 +
 +==== GPIO control ====
 +The LEDs can be turned on or off individually by configuring them as output GPIOs, then setting the GPIO level. ​
 +**Note**: GPIO 10 (green LED) defaults to the ''​status_led''​ function on Wahoo. It must be de-assigned to ''​none''​ before it can be used for another purpose. ​
 +
 +To setup the tri-color LEDs:
 +
 +^TruConnect commands^Comments^
 +|<​code>​
 +gfu 10 none
 +gfu 11 none
 +gfu 14 none
 +gfu 10 stdio
 +gfu 11 stdio
 +gfu 14 stdio
 +gdi 10 olo
 +gdi 11 olo
 +gdi 14 olo
 +</​code>​|<​code>​
 +Free up GPIO 10
 +Free up GPIO 11
 +Free up GPIO 14
 +Assign GPIO 10 to stdio function
 +Assign GPIO 11 to stdio function
 +Assign GPIO 14 to stdio function
 +Set red, green and blue GPIOs to output, ​
 +initial level low
 + 
 +</​code>​|
 +Now you can turn on separate red, green and blue leds by setting GPIO values with the [[commands#​gse|gse]] command. For example:
 +^TruConnect commands^Comments^
 +|<​code>​
 +gse 10 0
 +gse 11 0    ​
 +gse 14 1
 +</​code>​|<​code>​
 +Turn green off
 +Turn blue off
 +Turn red on
 +</​code>​|
 +
 +==== PWM control ====
 +To set the Wahoo tri-colour LED to a color combining the three LEDs, issue three [[commands#​pwm]] commands, one for each LED GPIO. 
 +
 +First set each of the LED GPIOs to ''​pwm''​ function with the [[commands#​gfu|gfu]] command:
 +
 +<​code>​
 +gfu 10 none
 +gfu 11 none
 +gfu 14 none
 +gfu 10 pwm
 +gfu 11 pwm
 +gfu 14 pwm
 +</​code>​
 +
 +The ratio of ''​low_count''​ and ''​high_count''​ arguments determines the duty cycle of the PWM, as described in the [[.commands#​pwm|pwm ]] command documentation. ​
 +The duty cycle impacts the brightness of the LED, lower duty cycles make the LED brighter. ​
 +The lowest available PWM frequency, about 128Hz, may be used without any detectable flashing of the LED.
 +
 +For example, to set the named color '​RebeccaPurple':​
 +<​code>​
 +pwm 14 614 409
 +pwm 10 818 205
 +pwm 11 409 614
 +</​code>​
 +
 +The [[.:​resources:​colortable| Color PWM Table]] shows the pwm commands for a sample color range.
 +
 +===== Speaker =====
 +
 +A speaker connected to a GPIO can be controlled with the PWM command or using the [[commands#​beep]] command. ​
 +
 +The Wahoo speaker tone is controlled via GPIO 13 and a PWM. The [[.commands#​pwm|pwm command]] documentation describes how to set the frequency and duty cycle of the PWM.
 +
 +To set the ''​pwm''​ function on GPIO 13:
 +<​code>​
 +gfu 13 none
 +gfu 13 pwm
 +</​code>​
 +
 +To play a middle C (C4), the command is:
 +<​code>​pwm 13 250 250</​code>​
 +
 +To turn the note off:
 +<​code>​pwm 13 stop</​code>​
 +
 +See the [[.:​resources:​musicalnotetable| Musical Note PWM Table]] for pwm commands to play a range of notes on the speaker.
 +
 +The [[commands#​beep|beep]] command plays a tone of specified length through a speaker. To use this command, the GPIO wired to the speaker must be set to ''​speaker''​ function with the [[.commands#​gfu|gfu]] command. See [[#​setting_gpio_function|Setting GPIO Function]] above. ​
 +
 +The following example shows how to set up the Wahoo speaker on GPIO 13 to allow the beep command, assuming GPIO 13 is currently set to another function:
 +
 +<​code>​
 +> gfu 13 none
 +Success
 +> gfu 13 speaker
 +Success
 +> save
 +Success
 +> reboot
 +[COMMAND MODE]
 +> beep 100
 +Success
 +</​code>​