Just like digital outputs, digital inputs are easy to control with a few lines of CircuitPython code. A great example of using digital inputs is reading the state of a button or switch. To do this you’ll need the following parts:

• A slide switch or toggle switch. These are switches that have three legs and physically connect one of the legs to another when the switch is flipped. You’ll see two different ways to wire this switch to your board–one that uses all three legs and another that uses just two legs.
• A breadboard and wires to connect the components and board together.

Wire up the switch to your board as follows:

• The middle leg or output of the switch is connected to one of the digital inputs of the board.
• Another leg of the switch is connected to the board’s ground or GND pin. When the switch is flipped to this position it will read a low digital logic signal.
• The opposite leg of the switch is connected to the board’s 3.3V output. You want to connect this switch to a voltage output that matches your board’s voltage for a high digital logic signal, typically 3.3V but sometimes 5V. When the switch is flipped to this position it will read a high digital logic signal.

Now connect to the board’s REPL and create a digital input object just like you saw previously with digital outputs. For example using pin A1 of a board:

By default digitalio.DigitalInOut objects are created as digital inputs so you don’t need to do anything else to read the switch. However if you were doing other things with the pin you can usedigitalio.DigitalInOut.direction property and set it to an input:

After a digital input object is created you simply read the digitalio.DigitalInOut.valueproperty to check if the input is at a high or low logic level. If the value is a boolean true value it’s at a high digital logic level and if it’s false it’s at a low digital logic level.

Try reading the switch state, for example you might see:

Then flip the switch to its opposite position and read it again:

Notice the value changed from false to true! This shows that the board first saw the digital input connected to low / ground logic level and then saw the input connected to high / 3.3V logic level. By flipping the switch you physically changed how the legs of the switch were connected to switch between high and low levels!

Remember you can use boolean values in conditional statements, like to print out a message if the switch is turned on:

There’s one other way to read the switch which only requires two of its legs to be connected to your board. This is useful to reduce the number of physical connections or to connect to momentary or push buttons that only have two legs. Change the wiring of the switch to look like:

• The middle leg or output of the switch is still connected to one of the digital inputs of the board.
• Another leg of the switch is connected to the board’s ground or GND pin.

The opposite leg of the switch remains disconnected–only two wires are connected to the switch. When the switch is wired like this it means it will read a ground or low logic level in one position, but what happens when it’s in the opposite position and not connected to anything on the board? This state is called ‘floating’ and the input will actually read random values–you might get a high or low logic level depending on the electrical noise around the pin!

Luckily there’s an easy way to prevent an input from floating by using special built-in pull-up or pull-down resistors available on most development board digital I/O pins. You can turn on a pull-up resistor that will bring the digital input up to a high digital logic level if nothing is connected to it. This prevents the input from floating and will instead read a high digital logic level. Then when the switch is flipped and connected to ground / low logic it will ‘overpower’ the small pull-up resistor and read a low digital logic level.

To enable a digital input with a pull-up (or pull-down) resistor you can do so with the digitalio.DigitalInOut.pull property:

Now the digital input is configured with a pull-up resistor! Try reading the value of the input with the  digitalio.DigitalInOut.valueattribute again:

Then flip the switch and read its value again:

Notice the switch value changes depending on how the switch is flipped. When the switch connects to ground you’ll read a false or low digital logic level, and when the switch connects to nothing (i.e. is floating) you’ll read a true or high logic level because of the pull-up resistor connected internally to 3.3V.

You don’t have to be limited to just pull-up resistors too. On some boards you can specify pull-down resistors that pull the input to a ground or low logic level, and you can even turn off the pull-up or pull-down. Just specify a different value for the pull parameter or attribute:

digitalio.Pull.UP

Set the input to have an internal pull-up resistor that reads a high digital logic level when nothing else is connected.

digitalio.Pull.DOWN

Set the input to have an internal pull-down resistor that reads a low digital logic level when nothing else is connected.

None

Remove any pull-up or pull-down resistor. The input will read whatever logic level is connected to it and ‘float’ to random high or low values if nothing is connected!

Alternative Usage

Above you saw how the digitalio.DigitalInOut.direction anddigitalio.DigitalInOut.pull properties let you set the input/output and pull-up or pull-down resistor state of a pin. As an alternative you can use the digitalio.DigitalInOut.switch_to_output() anddigitalio.DigitalInOut.switch_to_input() functions to also set the input/output and pull-up or pull-down resistor state. These functions are handy alternatives that can set both the direction and pull-up/pull-down state in one call (see the pull parameter to thedigitalio.DigitalInOut.switch_to_input() function).

Remember you can explicitly import Python objects to make your code more compact too, for example: