# Control Wiz Lights With CircuitPython ## Overview https://www.youtube.com/watch?v=Kc68RUhF8Eg Wiz smart lights and other brands that support the same controller app are readily available in stores and online. They're cheaper than some smart lights of yesteryear and they don't require any sort of base station beyond a WiFi access point. The lights provide several different ways to integrate and control them. This guide presents a CircuitPython library which uses a UDP connection over a WiFi network to send JSON data to the light which will tell it to take various actions. You initialize the WizConnectedLight object with the IP address of your light, then access and set properties to get its current current status and control the light. With this library you can easily set up control and light automation, and use button or sensor inputs to turn the lights on or off. You can even fetch data from online APIs like sunrise and sunset times, or other weather information and use it control the brightness or color temperature of the lights.  ## Parts To control the lights you can use any CircuitPython device with built-in WiFi. Several options that have been tested successfully with Wiz lights are listed below. ### Adafruit ESP32-S2 Feather - 4 MB Flash + 2 MB PSRAM [Adafruit ESP32-S2 Feather - 4 MB Flash + 2 MB PSRAM](https://www.adafruit.com/product/5000) What's Feather-shaped and has an ESP32-S2 WiFi module? What has a STEMMA QT connector for I2C devices? What has your favorite Espressif WiFi microcontroller and lots of Flash and RAM memory for your next IoT project? What will make your next IoT project flyyyyy? That's right -... In Stock [Buy Now](https://www.adafruit.com/product/5000) [Related Guides to the Product](https://learn.adafruit.com/products/5000/guides) ![Angled shot of rectangular microcontroller.](https://cdn-shop.adafruit.com/640x480/5000-12.jpg) ### Adafruit ESP32-S3 Feather with 4MB Flash 2MB PSRAM [Adafruit ESP32-S3 Feather with 4MB Flash 2MB PSRAM](https://www.adafruit.com/product/5477) The ESP32-S3 has arrived in Feather format - and what a great way to get started with this powerful new chip from Espressif! With dual 240 MHz cores, WiFi and BLE support, and native USB, this Feather is great for powering your IoT projects. That's right - it's the new... In Stock [Buy Now](https://www.adafruit.com/product/5477) [Related Guides to the Product](https://learn.adafruit.com/products/5477/guides) ![ESP32-S3 Feather with 4MB Flash 2MB PSRAM](https://cdn-shop.adafruit.com/640x480/5477-06.jpg) ### Adafruit ESP32-C6 Feather - STEMMA QT [Adafruit ESP32-C6 Feather - STEMMA QT](https://www.adafruit.com/product/5933) The ESP32-C6 is Espressif’s first Wi-Fi 6 SoC integrating 2.4 GHz Wi-Fi 6, Bluetooth 5 (LE) and the 802.15.4 protocol. It brings the goodness you know from the [low-cost C3 series](https://www.adafruit.com/product/5337) and improves it with Zigbee/802.15.4 at 2.4Ghz.... In Stock [Buy Now](https://www.adafruit.com/product/5933) [Related Guides to the Product](https://learn.adafruit.com/products/5933/guides) ![Angled shot of rectangular dev board.](https://cdn-shop.adafruit.com/640x480/5933-08.jpg) ### Raspberry Pi Pico 2W [Raspberry Pi Pico 2W](https://www.adafruit.com/product/6087) **Raspberry Pi Pico 2W** is Raspberry Pi Foundation's update to their popular RP2040-based wireless ico board, now built on **RP2350** : their new high-performance, secure microcontroller. With a higher core clock speed, double the on-chip SRAM (512KB), double... In Stock [Buy Now](https://www.adafruit.com/product/6087) [Related Guides to the Product](https://learn.adafruit.com/products/6087/guides) ![Angled Shot of the Raspberry Pi Pico 2W.](https://cdn-shop.adafruit.com/640x480/6087-00.jpg) ### Raspberry Pi Pico W [Raspberry Pi Pico W](https://www.adafruit.com/product/5526) The Raspberry Pi foundation changed single-board computing [when they released the Raspberry Pi computer](https://www.raspberrypi.org/archives/723), now they're ready to do the same for microcontrollers with the release of the brand new **Raspberry Pi Pico W**. This... In Stock [Buy Now](https://www.adafruit.com/product/5526) [Related Guides to the Product](https://learn.adafruit.com/products/5526/guides) ![Angled shot of a green microcontroller with castellated pads.](https://cdn-shop.adafruit.com/640x480/5526-01.jpg) ### Adafruit ESP32-S3 TFT Feather - 4MB Flash, 2MB PSRAM, STEMMA QT [Adafruit ESP32-S3 TFT Feather - 4MB Flash, 2MB PSRAM, STEMMA QT](https://www.adafruit.com/product/5483) We've got a new machine here at Adafruit, it can uncover your deepest desires. Don't believe me? I'll turn it on right now to prove it to you! What, you want your very own soft serve ice cream machine? OK well, that's not something we can provide. But we can provide your... Out of Stock [Buy Now](https://www.adafruit.com/product/5483) [Related Guides to the Product](https://learn.adafruit.com/products/5483/guides) ![Top view of a purple rectangular microcontroller with a color TFT screen and powered by an ESP32-S3 chip. It is also connected to a Li-Poly battery and a lux sensor breakout. The TFT display reads in colored text: "Adafruit Feather ESP32-S3 TFT Demo Battery: 3.8V / 45% I2C: 0xB, 0x10, "](https://cdn-shop.adafruit.com/640x480/5483-06.jpg) # Control Wiz Lights With CircuitPython ## Create Your settings.toml File CircuitPython works with WiFi-capable boards to enable you to make projects that have network connectivity. This means working with various passwords and API keys. As of [CircuitPython 8](https://circuitpython.org/downloads), there is support for a **settings.toml** file. This is a file that is stored on your **CIRCUITPY** drive, that contains all of your secret network information, such as your SSID, SSID password and any API keys for IoT services. It is designed to separate your sensitive information from your **code.py** file so you are able to share your code without sharing your credentials. CircuitPython previously used a **secrets.py** file for this purpose. The **settings.toml** file is quite similar. Warning: Your **settings.toml** file should be stored in the main directory of your **CIRCUITPY** drive. It should not be in a folder. ## CircuitPython **settings.toml** File This section will provide a couple of examples of what your **settings.toml** file should look like, specifically for CircuitPython WiFi projects in general. The most minimal **settings.toml** file must contain your WiFi SSID and password, as that is the minimum required to connect to WiFi. Copy this example, paste it into your **settings.toml** , and update: - `your_wifi_ssid` - `your_wifi_password` ```auto CIRCUITPY_WIFI_SSID = "your_wifi_ssid" CIRCUITPY_WIFI_PASSWORD = "your_wifi_password" ``` Many CircuitPython network-connected projects on the Adafruit Learn System involve using Adafruit IO. For these projects, you must _also_ include your Adafruit IO username and key. Copy the following example, paste it into your settings.toml file, and update: - `your_wifi_ssid` - `your_wifi_password` - `your_aio_username` - `your_aio_key` ```auto CIRCUITPY_WIFI_SSID = "your_wifi_ssid" CIRCUITPY_WIFI_PASSWORD = "your_wifi_password" ADAFRUIT_AIO_USERNAME = "your_aio_username" ADAFRUIT_AIO_KEY = "your_aio_key" ``` Some projects use different variable names for the entries in the **settings.toml** file. For example, a project might use `ADAFRUIT_AIO_ID` in the place of `ADAFRUIT_AIO_USERNAME`. **If you run into connectivity issues, one of the first things to check is that the names in the settings.toml file match the names in the code.** Warning: Not every project uses the same variable name for each entry in the **settings.toml** file! Always verify it matches the code. ## **settings.toml** File Tips Here is an example **settings.toml** file. ```auto # Comments are supported CIRCUITPY_WIFI_SSID = "guest wifi" CIRCUITPY_WIFI_PASSWORD = "guessable" CIRCUITPY_WEB_API_PORT = 80 CIRCUITPY_WEB_API_PASSWORD = "passw0rd" test_variable = "this is a test" thumbs_up = "\U0001f44d" ``` In a **settings.toml** file, it's important to keep these factors in mind: - Strings are wrapped in double quotes; ex: `"your-string-here"` - Integers are _ **not** _ quoted and may be written in decimal with optional sign (`+1`, `-1`, `1000`) or hexadecimal (`0xabcd`). - Floats (decimal numbers), octal (`0o567`) and binary (`0b11011`) are not supported. - Use `\u` escapes for weird characters, `\x` and `\ooo` escapes are not available in **.toml** files - Example: `\U0001f44d` for đź‘Ť (thumbs up emoji) and `\u20ac` for € (EUR sign) - Unicode emoji, and non-ASCII characters, stand for themselves as long as you're careful to save in "UTF-8 without BOM" format     When your  **settings.toml ** file is ready, you can save it in your text editor with the **.toml**  extension. ![adafruit_products_dotToml.jpg](https://cdn-learn.adafruit.com/assets/assets/000/117/071/medium640/adafruit_products_dotToml.jpg?1671034293) ## Accessing Your **settings.toml** Information in **code.py** In your **code.py** file, you'll need to `import` the `os` library to access the **settings.toml** file. Your settings are accessed with the `os.getenv()` function. You'll pass your settings entry to the function to import it into the **code.py** file. ```python import os print(os.getenv("test_variable")) ``` ![](https://cdn-learn.adafruit.com/assets/assets/000/117/072/medium800/adafruit_products_tomlOutput.jpg?1671034496) In the upcoming CircuitPython WiFi examples, you'll see how the **settings.toml ** file is used for connecting to your SSID and accessing your API keys. # Control Wiz Lights With CircuitPython ## Project Setup Are you new to using CircuitPython? No worries, [there is a full getting-started guide here](https://learn.adafruit.com/welcome-to-circuitpython "Welcome to CircuitPython"). Plug the device into your computer with a known good USB cable (not a charge-only cable). The device will appear to your computer in File Explorer or Finder (depending on your operating system) as a flash drive named  **CIRCUITPY**. If the drive does not appear, you can [install CircuitPython](https://learn.adafruit.com/welcome-to-circuitpython/installing-circuitpython) on your device and then return here. Download the project files with the Download Project Bundle button below. Unzip the file and copy/paste the  **code.py**  and other project files to your  **CIRCUITPY**  drive using File Explorer or Finder (depending on your operating system). ## Connect to WiFi In order to communicate with the Wiz light your CircuitPython device needs to be connected to WiFi on the same network as the light. The easiest way to do this is to include your WiFi network credentials in a **settings.toml** file. If that file doesn't exist, then create it. Add these entries to the file and fill in the details for your own WiFi network. ```auto CIRCUITPY_WIFI_SSID="network_name" CIRCUITPY_WIFI_PASSWORD="network_password" ``` Once that file is saved reboot your device and it will automatically connect to WiFi. ## Setup Wiz Light Install the Wiz smartphone app, available on both the Google Play and Apple app stores. Follow the prompts in the Wiz smartphone app to setup your light. You'll be prompted to enter a room name, and a name for the light, as well as your WiFi network credentials for the light to use to connect to the network. During "easy connect pairing", you'll need to ensure the light is powered off for at least 5 seconds, then turn it on and press the start button in the app to scan for nearby lights. Once the light is found, it can be saved into your room, and it will ask you for initial settings like default color temperature and fade times. Once completed, the light will be listed under the chosen room inside of the app. ### Find The Light IP Address Once your light has been paired with the app, you need to find its IP address. Launch the Wiz app on your smartphone and follow these steps. Note that your room and light names will differ from the ones in the screenshots. 1. Click the room that the light is in. 2. Long-press on the light. 3. Click settings in the menu that pops up. 4. Click the dropdown chevron near the light's name at the top. 5. Click "Device Info" 6. Find the IP address listed along with other information about the light. Once you've got your light's IP you'll need to fill it in to the line of code where the `WizConnectLight` is initialized. ![circuitpython_00_click_room.png](https://cdn-learn.adafruit.com/assets/assets/000/134/219/medium640/circuitpython_00_click_room.png?1734642928) ![circuitpython_01_longpress_light.png](https://cdn-learn.adafruit.com/assets/assets/000/134/220/medium640/circuitpython_01_longpress_light.png?1734642956) ![circuitpython_02_click_settings.png](https://cdn-learn.adafruit.com/assets/assets/000/134/221/medium640/circuitpython_02_click_settings.png?1734642969) ![circuitpython_03_click_dropdown.png](https://cdn-learn.adafruit.com/assets/assets/000/134/222/medium640/circuitpython_03_click_dropdown.png?1734642985) ![circuitpython_04_click_device_info.png](https://cdn-learn.adafruit.com/assets/assets/000/134/223/medium640/circuitpython_04_click_device_info.png?1734643012) ![circuitpython_05_find_ip.png](https://cdn-learn.adafruit.com/assets/assets/000/134/224/medium640/circuitpython_05_find_ip.png?1734643023) ## Drive Structure After copying the files, your drive should look like the listing below. It can contain other files as well, but must contain these at a minimum. ![Drive](https://github.com/adafruit/Adafruit_CircuitPython_Bundle/blob/folder-images/wiz_wiz_simpletest.py.png?raw=true ) ## Code The **code.py** for the Wiz library **simpletest** is shown below. This code will cycle through setting a few of the properties to demonstrate the capabilities of the library and validate connectivity. https://github.com/adafruit/Adafruit_CircuitPython_Wiz/blob/main/examples/wiz_simpletest.py # Control Wiz Lights With CircuitPython ## Button Remote Control This page details a basic remote control that can be made on a breadboard utilizing push-buttons. The example here is running on an Adafruit Feather ESP32-S2, but it could also work with an ESP32-S3 or ESP32-C6 based devices. The Pico W and Pico 2W can be used as well, but you will need to change the pin references in the code to whichever pins your wire your buttons to. ![](https://cdn-learn.adafruit.com/assets/assets/000/134/226/medium800/circuitpython_remote_control_photo_s.png?1734649738) ## Fritzing Diagram ![](https://cdn-learn.adafruit.com/assets/assets/000/134/227/medium800/circuitpython_remote_control_fritzing.png?1734649866) ## Code The **code.py** file for the remote control is shown below. Same as with the example on the previous page, you need to update the initialization line of code with the IP address of your own light, [see here](https://learn.adafruit.com/control-wiz-lights-with-circuitpython/project-setup#find-the-lights-ip-address-3189284 "Instructions to find Wiz light IP address") if you don't know the IP. https://github.com/adafruit/Adafruit_CircuitPython_Wiz/blob/main/examples/wiz_buttons_controller.py ## Neokey 1x4 Version If you like Stemma QT cables more than breadboards, there is an [alternate version](https://github.com/adafruit/Adafruit_CircuitPython_Wiz/blob/main/examples/wiz_neokey1x4_controller.py) of the remote control code that uses a [Neokey 1x4 QT](https://www.adafruit.com/product/4980 "Neokey 1x4 QT Product Link") instead of the breadboard and push-buttons. # Control Wiz Lights With CircuitPython ## Scanning For Lights If your network uses dynamic IP addresses, the IP for the light(s) could change on some frequency. For the prior examples in this guide that means you'd need to replace the IP address variable with the new IP each time it changes. If the IP changes often or you just don't like the hassle of finding the IP inside of the smartphone app you can use the scanning functionality within the Wiz CircuitPython library. The example code below will scan the network to find all connected Wiz lights and build a mapping of them with their MAC address. MAC addresses are static, so this will not change in the future. If you build scripts around this mechanism, it will continue to work even after the IP address of your devices change.  This example loops over all of the found lights and sets each to a random color. It can be easily modified to access individual lights within the MAC address map once you see the MAC address for your device printed out once. https://github.com/adafruit/Adafruit_CircuitPython_Wiz/blob/main/examples/wiz_scan_multiple_lights.py ## How Scanning Works The lights communicate over the network with the [UDP](https://en.wikipedia.org/wiki/User_Datagram_Protocol "User Datagram Protocol") protocol. Within this protocol there is functionality to broadcast a message to all devices on the network that are listening on a specific port. The library sends a broadcast on the port that the lights listen on, each light receives that message and replies with some basic info about itself including the MAC address and current IP address. ## Featured Products ### Adafruit ESP32-S3 Feather with 4MB Flash 2MB PSRAM [Adafruit ESP32-S3 Feather with 4MB Flash 2MB PSRAM](https://www.adafruit.com/product/5477) The ESP32-S3 has arrived in Feather format - and what a great way to get started with this powerful new chip from Espressif! With dual 240 MHz cores, WiFi and BLE support, and native USB, this Feather is great for powering your IoT projects. That's right - it's the new... In Stock [Buy Now](https://www.adafruit.com/product/5477) [Related Guides to the Product](https://learn.adafruit.com/products/5477/guides) ### Adafruit ESP32-S2 Feather - 4 MB Flash + 2 MB PSRAM [Adafruit ESP32-S2 Feather - 4 MB Flash + 2 MB PSRAM](https://www.adafruit.com/product/5000) What's Feather-shaped and has an ESP32-S2 WiFi module? What has a STEMMA QT connector for I2C devices? What has your favorite Espressif WiFi microcontroller and lots of Flash and RAM memory for your next IoT project? What will make your next IoT project flyyyyy? That's right -... In Stock [Buy Now](https://www.adafruit.com/product/5000) [Related Guides to the Product](https://learn.adafruit.com/products/5000/guides) ### Adafruit ESP32-C6 Feather - STEMMA QT [Adafruit ESP32-C6 Feather - STEMMA QT](https://www.adafruit.com/product/5933) The ESP32-C6 is Espressif’s first Wi-Fi 6 SoC integrating 2.4 GHz Wi-Fi 6, Bluetooth 5 (LE) and the 802.15.4 protocol. It brings the goodness you know from the [low-cost C3 series](https://www.adafruit.com/product/5337) and improves it with Zigbee/802.15.4 at 2.4Ghz.... In Stock [Buy Now](https://www.adafruit.com/product/5933) [Related Guides to the Product](https://learn.adafruit.com/products/5933/guides) ### Raspberry Pi Pico 2W [Raspberry Pi Pico 2W](https://www.adafruit.com/product/6087) **Raspberry Pi Pico 2W** is Raspberry Pi Foundation's update to their popular RP2040-based wireless ico board, now built on **RP2350** : their new high-performance, secure microcontroller. With a higher core clock speed, double the on-chip SRAM (512KB), double... In Stock [Buy Now](https://www.adafruit.com/product/6087) [Related Guides to the Product](https://learn.adafruit.com/products/6087/guides) ### Raspberry Pi Pico W [Raspberry Pi Pico W](https://www.adafruit.com/product/5526) The Raspberry Pi foundation changed single-board computing [when they released the Raspberry Pi computer](https://www.raspberrypi.org/archives/723), now they're ready to do the same for microcontrollers with the release of the brand new **Raspberry Pi Pico W**. This... In Stock [Buy Now](https://www.adafruit.com/product/5526) [Related Guides to the Product](https://learn.adafruit.com/products/5526/guides) ## Related Guides - [Adafruit ESP32-S2 Feather](https://learn.adafruit.com/adafruit-esp32-s2-feather.md) - [Adafruit ESP32-S3 Feather](https://learn.adafruit.com/adafruit-esp32-s3-feather.md) - [Adafruit ESP32-C6 Feather](https://learn.adafruit.com/adafruit-esp32-c6-feather.md) - [CircuitPython Web Workflow Code Editor Quick Start](https://learn.adafruit.com/getting-started-with-web-workflow-using-the-code-editor.md) - [TFT Spirit Board](https://learn.adafruit.com/tft-spirit-board.md) - [Espresso Water Tank Meter](https://learn.adafruit.com/espresso-water-tank-meter.md) - [ESP-NOW in CircuitPython](https://learn.adafruit.com/esp-now-in-circuitpython.md) - [IoT Filament Sensor](https://learn.adafruit.com/iot-filament-sensor.md) - [Networking in CircuitPython](https://learn.adafruit.com/networking-in-circuitpython.md) - [No-Code IoT Humidity and Temperature Sensor with Adafruit IO WipperSnapper](https://learn.adafruit.com/no-code-humidity-and-temp-tracker.md) - [Introducing Adafruit Feather](https://learn.adafruit.com/adafruit-feather.md) - [Feather Freezer Door Alarm](https://learn.adafruit.com/feather-door-alarm.md) - [Holiday IoT Switch](https://learn.adafruit.com/holiday-iot-switch.md) - [Adafruit USB Host FeatherWing with MAX3421E](https://learn.adafruit.com/adafruit-usb-host-featherwing-with-max3421e.md) - [No-Code IoT Pool Monitor](https://learn.adafruit.com/iot-pool.md) - [Twin Peaks Light Reactive Picture Frame](https://learn.adafruit.com/twin-peaks-light-reactive-pyportal-picture-frame.md)