Skip to main content

pin.configure(pinType, ...)

Configures one of the imp’s GPIO pins for a particular mode of operation

Availability

Device

Parameters

Name Type Description
pinType Constant The chosen mode of pin operation
... Various Multiple parameters to further define pin behavior, based on pin type

Returns

Nothing

Description

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 trigger a runtime error. 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:

Digital

pin.configure(outputMode, startingState)

Parameters Type Description
outputMode Constant One of the constants listed below
startingState Integer Optional starting state for the pin, default = 0. Available in impOS release 30

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. This optional parameter is only available in impOS release 30 and above.

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Ω.

pin.configure(inputMode, onPinStateChangeCallback)

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 and imp004m it is Pin W. 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.

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

Analog

pin.configure(ANALOG_OUT)

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.

pin.configure(ANALOG_IN)

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.

Pulse Width Modulation

pin.configure(PWM_OUT, period, dutyCycle, optionFlags)

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 (from impOS 38)

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:

Pins Min. Period* (Max. frequency) Max. Period (Min. frequency)
imp001/imp002 pin2/8/9 0.0000000667s (15MHz) 60s (0.0167Hz)
imp001/imp002 pin1/5/7/C 0.0000000333s (30MHz) 60s (0.0167Hz)
imp003 all PWM pins 0.0000000556s (18MHz) 60s (0.0167Hz)
imp004 pinA/D/M 0.0000000833s (12MHz) 60s (0.0167Hz)
imp004 pinB/K/N/P 0.0000000417s (24MHz) 60s (0.0167Hz)

* These are theoretical values: you would experience signal-integrity issues at such low periods.

The imp005 supports periods in the range 0.0000000534s to 0.001752s (18.7MHz to 571Hz). Note The imp005 only supports PWM from impOS 36 and up.

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.

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 from impOS 36 and up, on pins E-G, S, U and V.

PWM Options

On the imp004m only (running impOS 38 and up), 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, a Squirrel runtime error will be thrown.

The imp API methods pin.getperiod(), pin.getsteps() and pin.getdutycycle() continue to be available, even in Zombie mode.

pin.configure(PWM_OUT_STEPS, period, dutyCycle, stepCount)

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 from impOS 36 and up, on pins E-G, S, U and V.

Pulse Counter

pin.configure(PULSE_COUNTER, countDuration, division)

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.

Known Issue

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.

Pin-Triggered Pulse Generator (PTPG)

pin.configure(generatorMode, pin, delay, period)

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:

  • PTPG_OUT_ACTIVE_HIGH is held low for delay seconds then driven high for period seconds, before returning low
  • PTPG_OUT_ACTIVE_LOW is held high for delay seconds then driven low for period seconds, before returning high

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. A Squirrel runtime error occurs if the requested pulse duration is out of range. A Squirrel runtime error will also occur 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().

PTPG Example

// 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);