Configures one of the imp’s GPIO pins for a particular mode of operation
Device
| Name | Type | Description |
|---|---|---|
| pinType | Constant |
The chosen mode of pin operation
|
| ... | Various |
Multiple parameters to further define pin behavior, based on pin type
|
Nothing
This method configures one of the imp’s pins for a particular mode of operation. Not all modes are available on every pin; trying to configure a pin for a mode it doesn’t support will cause an exception to be thrown. See the imp pin mux for details and for information on the default state of a specific imp’s pins.
As the method’s subsequent parameters to pin.configure() depend on the mode selected using the first parameter, the variants are listed separately below by mode:
| Parameters | Type | Description |
|---|---|---|
| outputMode | Constant | One of the constants listed below |
| startingState | Integer | Optional starting state for the pin, default = 0 |
The pin is configured as a digital output pin that can be driven high or low using pin.write(1) and pin.write(0), respectively. If the optional second parameter is provided, the pin will be initialized with that value: again, 1 for high or 0 for low, equivalent to pin.write(1) and pin.write(0), respectively.
A digital output pin can be configured with any of the following constants, depending on the behavior you require:
| Output Mode Constant | Value | Description |
|---|---|---|
| DIGITAL_OUT | 1024 | ‘Normal’ (push-pull) digital output |
| DIGITAL_OUT_OD | 1280 | Open-drain digital output |
| DIGITAL_OUT_OD_PULLUP | 1536 | Open-drain digital output with internal pull-up |
The values assigned to the constants may change in a future impOS release.
Internal pull-ups are 40kΩ ±10kΩ.
| Name | Type | Description |
|---|---|---|
| inputMode | Constant | One of the constants listed below |
| callback | Function | Optional callback that is executed when pin state changes. The function has no parameters |
The pin is configured as a digital input pin, with an optional callback function that will be executed whenever the state of the pin changes. On the imp001, imp002 and imp005 (Murata part number LBWA1UZ1GC-901), all accessible pins can be assigned such a callback. However, on the imp003 (Murata part number LBWA1ZV1CD), only certain pins may be assigned a callback: pins A through E, G, M, P, Q, R and T through X. The imp004m (Murata part number LBEE5ZZ1MD) supports callbacks with pins B-E, H, L and P-W.
A digital input pin can be configured with any of the following constants, depending on the behavior you require:
| Input Mode Constant | Value | Description |
|---|---|---|
| DIGITAL_IN | 256 | Floating (tri-state) digital input |
| DIGITAL_IN_PULLUP | 512 | Digital input with internal pull-up |
| DIGITAL_IN_PULLDOWN | 768 | Digital input with internal pull-down |
| DIGITAL_IN_WAKEUP | 2560 | Wake-up pin only. Digital input with internal pull-down. An imp in Deep Sleep will be woken by logic high on the wake-up pin if it was configured with this before sleep |
The values assigned to the constants may change in a future impOS release.
The DIGITAL_IN_WAKEUP option only applies to the imp’s specific wake-up in. On the imp001 and imp002 devices this is pin 1. On the imp003, imp004m and imp006 it is Pin W; the imp006 also allows pin V to be used this way. Waking the imp from Deep Sleep restarts Squirrel afresh, so any (optional) pin state-change callback registered with the method will not be called. However, if the pin is triggered while the imp is awake, the callback will be called.
Note The imp005 does not support Deep Sleep and does not offer a wake pin.
The callback is not a true interrupt: it doesn’t interrupt or pre-empt any Squirrel code that is already running. If some other Squirrel code is running when the input changes state, the callback will be queued and will run when the imp is next idle.
All callbacks, pull-ups and pull-downs are disabled in deep sleep, except that the pull-down is enabled when configured as DIGITAL_IN_WAKEUP
The pin is configured as an analog (DAC) output. Use pin.write() to set the output voltage: pass in a value between 0.0 and 1.0, where 0.0 corresponds to 0V and 1.0 corresponds to the imp power supply voltage (usually 3.3V).
On the imp001 and imp002, only pins 1 and 5 support analog output. On the imp003 only pins A and C support analog output. No imp004m pins support analog output. No imp005 pins support analog output.
The pin is configured as an analog (ADC) input. Use pin.read() to return an integer between 0 and 65,535 (16 bits), where 0 corresponds to 0.0V and 65,535 corresponds to the imp’s power supply voltage (usually 3.3V).
On the imp002 and imp003 modules only certain pins support analog input. For the imp002, these are 1, 2, 5, 7, 9, A and B. For the imp003, pins A, B, C, E, F, H, J, K, N and W support analog input. All imp001 pins support analog input. The imp004m supports analog input on pins A-D, K, L and W. No imp005 pins support analog input.
| Name | Type | Description |
|---|---|---|
| PWM_OUT | Constant | The chosen PWM mode |
| period | Float | The modulation period in seconds |
| dutyCycle | Float | A value between 0.0 and 1.0 |
| optionFlags | String | Extra settings; see PWM Options, below |
The pin is configured to be a frequency priority pulse width modulation output pin. The desired frequency (period) is set precisely and the number of steps (different effective duty cycles) within that frequency is made as large as possible. The imp001 through imp004m support periods as follows:
| imp | Pins | Min. Period* (Max. frequency) | Max. Period (Min. frequency) |
|---|---|---|---|
| imp001 | pin2/8/9 | 0.0000000667s (15MHz) | 60s (0.0167Hz) |
| imp001 | pin1/5/7 | 0.0000000333s (30MHz) | 60s (0.0167Hz) |
| imp002 | pin2/8/9 | 0.0000000667s (15MHz) | 60s (0.0167Hz) |
| imp002 | pin1/5/7/C | 0.0000000333s (30MHz) | 60s (0.0167Hz) |
| imp003 | pinB/C/E/F/K/L/M | 0.0000000556s (18MHz) | 60s (0.0167Hz) |
| imp004m | pinA/D/M | 0.0000000833s (12MHz) | 60s (0.0167Hz) |
| imp004m | pinB/K/N/P | 0.0000000417s (24MHz) | 60s (0.0167Hz) |
| imp005 | pinE/F/G/S/U/V | 0.0000000534s (18.7MHz) | 0.001752 (571Hz) |
| imp006 | pinR/XA/XB/XN | 0.0000000833s (12MHz) | 60s (0.0167Hz) |
| imp006 | pinJ/N/T/U | 0.0000000417s (24MHz) | 60s (0.0167Hz) |
* These are theoretical values: you would experience signal-integrity issues at such low periods.
The actual period and number of steps, after any necessary approximation, can be obtained from pin.getperiod() and pin.getsteps().
Following configuration, you must call pin.write() to begin the modulation. The value passed into the method is the duty cycle, from 0.0 to 1.0. This is then rounded to the nearest available value.
All PWM pins can be configured individually, and they can all be set to different frequencies if required.
On the imp004m only, pin.configure(PWM_OUT, ...) has an extra parameter, optionFlags. This parameter is optional and takes as an argument a string which indicates how the PWM_OUT configuration may be further modified.
At this time, only one such modification is available. It is applied by passing the string "ZOMBIE" into optionFlags. This causes the PWM to operate in ‘zombie’ mode: it outputs continuously at the most recent period and duty-cycle set by either pin.configure() or pin.write(), even across Squirrel reloads, firmware upgrades and resets. This allows PWM-based applications such as lighting to operate without perceptible flicker when such a restart occurs. This mode can only be unset by re-configuring the pin to some other role, by putting the imp into a deep sleep, or by power-cycling the imp.
Even if a PWM is continuing to run as a zombie from a previous Squirrel session, Squirrel must still call pin.configure() once to set up the pin before making any calls to pin.write().
Even a zombie PWM will drop out briefly during the course of a Squirrel reload or a firmware upgrade, but the drop-outs are tested as being shorter than five milliseconds.
Only one PWM at a time can be set to zombie operation, which is not available with the PWM_OUT_STEPS mode (see below). If Squirrel does not recognize the argument passed into optionFlags, an exception will be thrown.
The imp API methods pin.getperiod(), pin.getsteps() and pin.getdutycycle() continue to be available, even in Zombie mode.
| Name | Type | Description |
|---|---|---|
| PWM_OUT_STEPS | Constant | The chosen PWM mode |
| period | Float | The modulation period in seconds |
| dutyCycle | Float | A value between 0.0 and 1.0 |
| stepCount | Integer | Number of steps into which the range is divided (up to 65,535) |
The pin is configured to be a steps priority pulse width modulation output pin. The desired number of steps is set precisely, and the frequency (period) is approximated, if necessary.
The actual period and number of steps, after any necessary approximation, can be obtained from pin.getperiod() and pin.getsteps().
Following configuration, you must call pin.write() to begin the modulation. The value passed into the method is a duty ratio from 0.0 to 1.0. This is then rounded to the nearest available value.
All PWM pins can be configured individually, and they can all be set to different frequencies if required.
All pins on the imp001 support PWM, but only certain pins on the imp002 and imp003 modules do so. For the imp002, pins 1, 2, 5, 7, 9 and C support PWM. For the imp003, pins B, C, E, F, K, L and M support PWM. The imp004m supports PWM on pins A, B, D, K and M-P. The imp005 only supports PWM on pins E-G, S, U and V.
| Name | Type | Description |
|---|---|---|
| PULSE_COUNTER | Constant | The chosen Pulse Count mode |
| countDuration | Float | The sample period in seconds |
| division | Integer | Optional division (default = 1) |
The pin — it must be pin 1 on the imp001 and imp002 modules; pin J on the imp004m; the imp003 and imp005 have no pulse counter — is configured as a timed pulse-counter. Whenever pin.read() is called, it samples the pin for the duration (in seconds) specified by the countDuration parameter, counting pulses on their rising edges. The pulse count can be divided down in hardware if a vast number of pulses are expected.
Note The impC001 currently does not support the configuration of any of its GPIO pins as pulse counters.
Re-configuring the pulse counter (using pin.configure()) to use a different sample duration causes the pulse counter to miss count the pulses received during the specified duration. This behavior is still seen even if you reconfigure the pin as DIGITAL_IN between pulse-counter configuration call.
Expected Fix This issue is scheduled to be addressed in a future impOS release.
| Name | Type | Description |
|---|---|---|
| generatorMode | Constant | Mode constant: PTPG_OUT_ACTIVE_HIGH or PTPG_OUT_ACTIVE_LOW |
| pin |
pin object | The trigger: a pin object already configured as DIGITAL_IN, DIGITAL_IN_PULLUP or DIGITAL_IN_PULLDOWN |
| delay | Float | The Delay in seconds from the transition of trigger pin to the assertion of this pin |
| period | Float | The duration in seconds of the PTPG pin assertion |
The pin is configured as a pin-triggered pulse generator (PTPG) digital output. Applications include low-power AC dimming, where the trigger pin is driven by the 3.3V digital output of a zero-crossing detection circuit.
After a rising or falling transition on the trigger pin:
The output pulse is restarted immediately if another transition occurs on the trigger pin.
Changes to delay — using pin.write() — are applied on the next transition of the trigger pin.
The resolution and range of the output pulse are 1μs and 65.5ms respectively. An exception will be thrown if the requested pulse duration is out of range. An exception will also be thrown if the trigger pin is not a digital input, is already configured to another PTPG output, or is repurposed while PTPG outputs remain configured.
The following pin combinations are supported on the imp001 and imp002:
| Trigger pin | PTPG output pin(s) |
|---|---|
| 5 | 7 |
| 8 | 5, 9 or (imp002) C |
| 9 | 2 |
The following pin combinations are supported on the imp003:
| Trigger pin | PTPG output pin(s) |
|---|---|
| E | C |
| F | K or X |
| L | G |
| M | D |
The following pin combinations are supported on the imp004m:
| Trigger pin | PTPG output pin(s) |
|---|---|
| A | W |
| B | C |
| M | N or P |
Note Neither the imp005 nor the impC001 support PTPG operation.
When a pin is in PTPG mode, the current value of delay can be read using pin.getdelay(), and period using pin.getperiod().
// Configure the imp001 trigger pin to DIGITAL_IN
hardware.pin8.configure(DIGITAL_IN);
// Configure imp001 PTPG to 33% duty @ 60Hz, 10us output pulse
hardware.pin5.configure(PTPG_OUT_ACTIVE_HIGH, hardware.pin8, 0.0055, 0.0001);