It's easy to use the Adafruit AW9523 GPIO Expander and LED Driver Breakout with CircuitPython and the Adafruit CircuitPython AW9523 module. This module allows you to easily write Python code that reads temperature and humidity data from the sensor.

You can use this sensor with any CircuitPython microcontroller board or with a computer that has GPIO and Python thanks to Adafruit_Blinka, our CircuitPython-for-Python compatibility library.

CircuitPython Microcontroller Wiring

First wire up an AW9523 to your board exactly as follows. Here is an example of the AW9523 wired to a Feather using I2C:

Board 3V to breakout VIN (red wire)
Board GND to breakout GND (black wire)
Board SCL to breakout SCL (yellow wire)
Board SDA to breakout SDA (blue wire)

Python Computer Wiring

Since there's dozens of Linux computers/boards you can use we will show wiring for Raspberry Pi. For other platforms, please visit the guide for CircuitPython on Linux to see whether your platform is supported.

Here's the Raspberry Pi wired with I2C:

Pi 3V to breakout VIN (red wire)
Pi GND to breakout GND (black wire)
Pi SCL to breakout SCL (yellow wire)
Pi SDA to breakout SDA (blue wire)

CircuitPython Installation of AW9523 Library

You'll need to install the Adafruit CircuitPython AW9523 library on your CircuitPython board.

First make sure you are running the latest version of Adafruit CircuitPython for your board.

Next you'll need to install the necessary libraries to use the hardware--carefully follow the steps to find and install these libraries from Adafruit's CircuitPython library bundle. Our CircuitPython starter guide has a great page on how to install libraries from the library bundle.

Copy the following file from the bundle to the lib folder on your CIRCUITPY drive:

adafruit_aw9523.mpy

Also copy the following folder (not its individual contents, but the whole folder itself) into lib:

adafruit_register

Before continuing make sure your board's lib folder or root filesystem has both the adafruit_aw9523.mpy file and adafruit_register folder copied over.

Python Installation of AW9523 Library

You'll need to install the Adafruit_Blinka library that provides the CircuitPython support in Python. This may also require enabling I2C on your platform and verifying you are running Python 3. Since each platform is a little different, and Linux changes often, please visit the CircuitPython on Linux guide to get your computer ready!

Once that's done, from your command line run the following command:

pip3 install adafruit-circuitpython-aw9523

If your default Python is version 3 you may need to run 'pip' instead. Just make sure you aren't trying to use CircuitPython on Python 2.x, it isn't supported!

CircuitPython & Python Usage

To demonstrate the usage of this breakout, you have two examples to choose from: I/O using a button and an LED, and constant current fade.

Button and LED

This example shows how you can create an output and an input on the expander. Note that this expander does not support internal pull resistors.

Connect an LED to pin 0, with a resistor to ground, this is the output.

Connect a tactile switch with one side connected to pin 1 of the expander. Add a ~10K pull-up resistor on the expander pin 1 to Vin. Connect the other side of the button to ground. This makes it so the button pin is HIGH by default, and when you press the button, the pin goes LOW.

LED+ to breakout GPIO 0
LED- to 1K resistor
1K resistor to breadboard ground rail
One leg of button to breadboard ground rail
Other leg of button to breakout GPIO 1 + 10K pull-up resistor
10K pull-up resistor to breadboard VIN rail

Save the following as code.py on your CIRCUITPY drive.

Download Project Bundle

Copy Code

# SPDX-FileCopyrightText: Copyright (c) 2020 ladyada for Adafruit Industries
#
# SPDX-License-Identifier: MIT

import board
import digitalio
import adafruit_aw9523

i2c = board.I2C()  # uses board.SCL and board.SDA
# i2c = board.STEMMA_I2C()  # For using the built-in STEMMA QT connector on a microcontroller
aw = adafruit_aw9523.AW9523(i2c)

led_pin = aw.get_pin(0)  # LED on AW9523 io 0
button_pin = aw.get_pin(1)  # Button on AW io 1

# LED is an output, initialize to high
led_pin.switch_to_output(value=True)
# Button is an input, note pull-ups are not supported!
button_pin.direction = digitalio.Direction.INPUT

while True:
    # LED mirrors button pin
    led_pin.value = button_pin.value

# SPDX-FileCopyrightText: Copyright (c) 2020 ladyada for Adafruit Industries
#
# SPDX-License-Identifier: MIT

import board
import digitalio
import adafruit_aw9523

i2c = board.I2C()  # uses board.SCL and board.SDA
# i2c = board.STEMMA_I2C()  # For using the built-in STEMMA QT connector on a microcontroller
aw = adafruit_aw9523.AW9523(i2c)

led_pin = aw.get_pin(0)  # LED on AW9523 io 0
button_pin = aw.get_pin(1)  # Button on AW io 1

# LED is an output, initialize to high
led_pin.switch_to_output(value=True)
# Button is an input, note pull-ups are not supported!
button_pin.direction = digitalio.Direction.INPUT

while True:
    # LED mirrors button pin
    led_pin.value = button_pin.value

Now, press the button. The LED lights up! The LED mirrors the button, so when the button is pressed, the LED lights up.

Constant Current Fade

This example shows how to set up all the pins to use them as a constant-current driver for LEDs. This is great for flicker-free LED driving, and consistent brightness no matter what the voltage is.

In this example, connect LEDs to each expander pin.

Connect the cathode (negative) leg of the LED to the numbered GPIO pad, then the anode (positive) to power

Note that you do not need resistors with the LEDs because we are limiting the current internally. However, there's no harm if the LED has a resistor.

adafruit_products_AW9523_Feather_I2C_cont_current_LEDs_bb.jpg

Constant current mode is open drain sink ONLY. That means you must connect LED negative sides to the pin and the positive sides to power - this is opposite from how we normally drive LEDs from a GPIO pin

Save the following as code.py on your CIRCUITPY drive.

Download Project Bundle

Copy Code

# SPDX-FileCopyrightText: Copyright (c) 2020 ladyada for Adafruit Industries
#
# SPDX-License-Identifier: MIT

import busio
import board
import adafruit_aw9523

i2c = busio.I2C(board.SCL, board.SDA)
aw = adafruit_aw9523.AW9523(i2c)
print("Found AW9523")

# Set all pins to outputs and LED (const current) mode
aw.LED_modes = 0xFFFF
aw.directions = 0xFFFF

n = 0
while True:
    for pin in range(16):
        # every LED is 'offset' by 16 counts so they dont all pulse together
        aw.set_constant_current(pin, (pin * 16 + n) % 256)
    # n increments to increase the current from 0 to 255, then wraps around
    n = (n + 1) % 256

# SPDX-FileCopyrightText: Copyright (c) 2020 ladyada for Adafruit Industries
#
# SPDX-License-Identifier: MIT

import busio
import board
import adafruit_aw9523

i2c = busio.I2C(board.SCL, board.SDA)
aw = adafruit_aw9523.AW9523(i2c)
print("Found AW9523")

# Set all pins to outputs and LED (const current) mode
aw.LED_modes = 0xFFFF
aw.directions = 0xFFFF

n = 0
while True:
    for pin in range(16):
        # every LED is 'offset' by 16 counts so they dont all pulse together
        aw.set_constant_current(pin, (pin * 16 + n) % 256)
    # n increments to increase the current from 0 to 255, then wraps around
    n = (n + 1) % 256

All of the LEDs light up in a pattern.

The aw.set_constant_current(pin, (pin * 16 + n) % 256) plus n = (n + 1) % 256 will cause the LEDs on each pin to fade up from 0 (no current) to 255 (max current), then fade back down. The fade on each pin is offset by 16 counts so they don't all pulse together.