# Sensor-Locked Secrets with CircuitPython

## Overview

![Adafruit Feather ESP32S3 connected to a MAX44009 light sensor via STEMMA QT cable. The display shows seemingly random characters of garbled text. A light shines on the sensor and the text is revealed once the lux reaches 800](https://cdn-learn.adafruit.com/assets/assets/000/144/090/medium800thumb/temperature___humidity_lux_decrypt_text.jpg?1778096934 )

This project is about scrambling a secret message or picture in such a way that it can only be decrypted when certain environmental factors are met. The guide covers three different types of sensor inputs: GPS coordinates, lux light values, and temperature/humidity/CO2 readings. The general concept could be adapted for other types of sensors like magnetic, gyroscope, proximity and more.

The inspirations for this project include [reverse geo-cache puzzles](https://www.geocaching.com/blog/2010/12/one-year-later-the-story-of-the-first-reverse-geocache-puzzle-box/) like the one in [this learn guide](https://learn.adafruit.com/reverse-geocache-engagement-box/overview), and statues that are engineered to use the sun's location at specific day and time to create a special effect with shadows or sun beams. A few historical examples of the latter are ‘the descent of Kukulcán’ serpent effect on the Kukulcán pyramid in Chichén Itzá Mexico, and the&nbsp;[inner chamber illumination at Newgrange](https://www.newgrange.com/winter_solstice.htm) in County Meath Ireland.

## Parts
### 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)

### Adafruit Ultimate GPS FeatherWing

[Adafruit Ultimate GPS FeatherWing](https://www.adafruit.com/product/3133)
Give your Feather a sense of place, with an Ultimate GPS FeatherWing. <!--EndFragment-->In 2013 we designed the [Ultimate GPS module](https://www.adafruit.com/products/746) to satisfy all your GPS desires - and now we have brought its power and versatility plus more to our...

In Stock
[Buy Now](https://www.adafruit.com/product/3133)
[Related Guides to the Product](https://learn.adafruit.com/products/3133/guides)
![Angled shot of long, rectangular GPS-enabled add-on board.](https://cdn-shop.adafruit.com/640x480/3133-09.jpg)

### Adafruit MAX44009 Wide-range Lux Light Sensor - 188,000 Lux Max

[Adafruit MAX44009 Wide-range Lux Light Sensor - 188,000 Lux Max](https://www.adafruit.com/product/6498)
This is an easy to use&nbsp;lux sensor, and features an ultra-wide 22-bit dynamic range from 0.045  
lux to 188,000 lux. That means you can use the **&nbsp;Adafruit MAX44009 Wide-range Lux Sensor&nbsp;** in darkness or in bright outdoors sun, without having to tweak the...

In Stock
[Buy Now](https://www.adafruit.com/product/6498)
[Related Guides to the Product](https://learn.adafruit.com/products/6498/guides)
![Angled Shot of the Adafruit MAX44009 Wide-range Lux Sensor.](https://cdn-shop.adafruit.com/640x480/6498-00.jpg)

### Adafruit STCC4 and SHT41 - CO2, Temperature & Humidity Sensor

[Adafruit STCC4 and SHT41 - CO2, Temperature & Humidity Sensor](https://www.adafruit.com/product/6478)
CO₂&nbsp;sensors are essential for determining if a room is too 'stuffy' - high CO₂ makes humans grumpy and tired. That's why it's always nice to take a deep breath outside where CO₂ is about 400 ppm. However, until now, CO₂ sensors were always really chunky (<a...></a...>

In Stock
[Buy Now](https://www.adafruit.com/product/6478)
[Related Guides to the Product](https://learn.adafruit.com/products/6478/guides)
![Angled shot of CO2, temperature, and humidity sensor breakout.](https://cdn-shop.adafruit.com/640x480/6478-02.jpg)

### FeatherWing Doubler - Prototyping Add-on For All Feather Boards

[FeatherWing Doubler - Prototyping Add-on For All Feather Boards](https://www.adafruit.com/product/2890)
This is the **FeatherWing Doubler** - a prototyping add-on and more for all Feather boards. This is similar to our [FeatherWing Proto](https://www.adafruit.com/products/2884) except there are two! The magic of the Doubler comes when stacking a Feather and another...

In Stock
[Buy Now](https://www.adafruit.com/product/2890)
[Related Guides to the Product](https://learn.adafruit.com/products/2890/guides)
![Double prototyping feather wing PCB with socket headers installed](https://cdn-shop.adafruit.com/640x480/2890-01.jpg)

### USB Type A to Type C Cable - 1ft - 0.3 meter

[USB Type A to Type C Cable - 1ft - 0.3 meter](https://www.adafruit.com/product/4473)
As technology changes and adapts, so does Adafruit. This&nbsp;&nbsp; **USB Type A to Type C** cable will help you with the transition to USB C, even if you're still totin' around a USB Type A hub, computer or laptop.

USB C is the latest industry-standard connector for...

In Stock
[Buy Now](https://www.adafruit.com/product/4473)
[Related Guides to the Product](https://learn.adafruit.com/products/4473/guides)
![Angled shot of a one-foot-long, black, USB Type A to Type C Cable](https://cdn-shop.adafruit.com/640x480/4473-02.jpg)

# Sensor-Locked Secrets with CircuitPython

## Installing CircuitPython

[CircuitPython](https://github.com/adafruit/circuitpython) is a derivative of [MicroPython](https://micropython.org) designed to simplify experimentation and education on low-cost microcontrollers. It makes it easier than ever to get prototyping by requiring no upfront desktop software downloads. Simply copy and edit files on the **CIRCUITPY** drive to iterate.

## CircuitPython Quickstart

Follow this step-by-step to quickly get CircuitPython running on your board.

[Download the latest version of CircuitPython for this board via circuitpython.org](https://circuitpython.org/board/adafruit_feather_esp32s3_tft/)
 **Click the link above to download the latest CircuitPython UF2 file.**

Save it wherever is convenient for you.

![install_circuitpython_on_most_boards_CircuitPython_downloaded.jpg](https://cdn-learn.adafruit.com/assets/assets/000/102/129/medium640/install_circuitpython_on_most_boards_CircuitPython_downloaded.jpg?1620922559)

![](https://cdn-learn.adafruit.com/assets/assets/000/114/082/medium800/adafruit_products_FS3TFT_NeoPixel_and_reset_button.jpg?1660235941)

Plug your board into your computer, using a known-good data-sync cable, directly, or via an adapter if needed.

Double-click the **reset** button (highlighted in red above), and you will see the **RGB status LED(s)** turn green (highlighted in green above). If you see red, try another port, or if you're using an adapter or hub, try without the hub, or different adapter or hub.

For this board, **tap reset and wait for the LED to turn purple, and as soon as it turns purple, tap reset again**. The second tap needs to happen while the LED is still purple.

If double-clicking doesn't work the first time, try again. Sometimes it can take a few tries to get the rhythm right!

A lot of people end up using charge-only USB cables and it is very frustrating! **Make sure you have a USB cable you know is good for data sync.**

You will see a new disk drive appear called **FTHRS3BOOT**.

&nbsp;

&nbsp;

Drag the **adafruit\_circuitpython\_etc.uf2** file to **FTHRS3BOOT**.

![adafruit_products_FS3TFT_UF2_downloaded.png](https://cdn-learn.adafruit.com/assets/assets/000/114/085/medium640/adafruit_products_FS3TFT_UF2_downloaded.png?1660236285)

![adafruit_products_FS3TFT_drag_UF2.png](https://cdn-learn.adafruit.com/assets/assets/000/114/086/medium640/adafruit_products_FS3TFT_drag_UF2.png?1660236295)

The **BOOT** drive will disappear and a new disk drive called **CIRCUITPY** will appear.

That's it!

![install_circuitpython_on_most_boards_CIRCUITPY.jpg](https://cdn-learn.adafruit.com/assets/assets/000/102/130/medium640/install_circuitpython_on_most_boards_CIRCUITPY.jpg?1620923145)

# Sensor-Locked Secrets with CircuitPython

## How It Works

The project supports encrypting a text message or an image file. The cipher used differs between them, but the key derivation works similarly. The key is generated by finding the [SHA-256 hash](https://en.wikipedia.org/wiki/SHA-2) of the sensor reading range (ex: `200-300`) or GPS coordinates (ex:&nbsp;`40.656,-74.007`).

## Text Secrets

Text messages use the [Vigenère cipher](https://en.wikipedia.org/wiki/Vigen%C3%A8re_cipher) modified to support the full range of printable ASCII characters instead of just letters A-Z. This cipher outputs scrambled, but printable, text when an attempt to decrypt with the incorrect key is made. It's perfect for this project because it shows mysterious text as a clue that a secret message is hidden within. Vigenère cipher can use a key of any length. The key must use the same alphabet of characters that the encrypted message does. In this case, the ASCII printable characters in the ID range 32-126 from **space** to **tilde** in the&nbsp;[ASCII chart](https://www.ascii-code.com/). SHA-256 produces a 256-bit (32 byte) hash containing raw byte values which aren't restricted to printable ASCII. To work around this, the base64 representation of the hash is used as the Vigenère key. For example, a generated key looks something like this:

`PdToaSE3R9V9ClRENwNMhYV+ihPv5NXt05kQo8VrbH8=`

Once you have the key, encrypting a message with the Vigenère cipher is done by looking up each clear text characters cipher text counterpart in the Vigenère table or&nbsp;[tabula recta](https://en.wikipedia.org/wiki/Tabula_recta). Each successive character that is encoded uses a row from the table matching the next character from the key, which gives the cipher its [polyalphabetic](https://en.wikipedia.org/wiki/Polyalphabetic_cipher) property. That increases its resilience against basic frequency analysis, and makes repeated clear text characters come out looking scrambled and non-repetitive in the cipher text.

## Image File Secrets

Image files contain raw binary data instead of only printable text characters. Modern cryptography ciphers were made for the computer age and support encrypting raw data. [AES](https://en.wikipedia.org/wiki/Advanced_Encryption_Standard) is one such modern cipher. It's used by this project for encrypting images. Under normal circumstances, an entire file would be encrypted with AES, making it completely unreadable and unable to be successfully rendered as an image in common applications.

The image file contains metadata like encoding type, size, and color palette which are necessary for rendering it. To avoid completely non-functional image files, only the pixel data is encrypted. The rest of the metadata remains intact. As a result, the display will show a scrambled image that resembles TV static whenever the key is wrong, instead of being entirely broken with only an error message about a corrupt file.

One of the variations of AES accepts a 256-bit (32 byte) key, which is conveniently exactly what is output by the SHA-256 hashing algorithm. That means the raw bytes of the hash can be used as the key directly instead of having to convert them to base64 or any other representation. Here is an example of what the AES key could look like:

`b'9\x0b6|\xf2\xc3Cg\xca\xb5}I3,m\xcb\x0f\x8e\xb7\xb1\x08J`\xcb\x84\xd1]E\xeb\xe4\xe4\x8a'`

The code attempts to decrypt the pixel data using a key derived from the current sensor reading, then uses&nbsp;[bitmaptools.arrayblit()](https://docs.circuitpython.org/en/latest/shared-bindings/bitmaptools/#bitmaptools.arrayblit) to copy the resulting pixels into a `displayio.Bitmap` so that it can be shown on the display. If the key was incorrect, the Bitmap will look like random pixel noise. If the key was correct, the original image will be revealed.

# Sensor-Locked Secrets with CircuitPython

## Encrypting Secrets

The different versions of CircuitPython microcontroller code for this project support different sensor breakouts for decoding the secret messages. The same encryptor page can be used to encode secrets for all of them.&nbsp;

The page can be used to encrypt multiple messages/images with different values. Each encrypted secret gets copied into a `SEQUENCE` list inside of the **code.py** file.

Once a secret has been revealed successfully, it remains visibly decrypted on the screen until the user presses the **BOOT** button on the Feather to advance to the next puzzle in the sequence.

![Adafruit Feather S3 TFT with the BOOT button highlighted.](https://cdn-learn.adafruit.com/assets/assets/000/144/089/medium640/temperature___humidity_boot_button_advance.png?1778093440)

Click the button bellow access the encryptor page.

[Encryptor Page](https://adafruit.github.io/Sensor_Locked_Secrets_Encryptor/)
The page contains two tabs: one for encoding text, the other for encoding images.

## Text Secrets
For text secrets, fill in the following fields and then press the **Encrypt** button.

- Reading type - a dropdown. Select **Temperature** , **Humidity** , **CO2** , **Lux** , or **Other** based on the type of sensor/data reading you want to unlock the secret.
- Precision level - an integer number. Larger numbers result in a wider range of successful decryption values, `1` means the value must fall between two consecutive values i.e. `22-23`. Whereas `10` would mean a range of 10 values like `42-52`. For GPS, the precision level is used for the number of decimal places in the coordinates i.e. `40.656,-74.007` is `3` decimals.
- Sensor value - a float number. The target sensor reading for unlocking the secret. The actual key will be derived from a range that covers the target value based on the precision level.
- Plaintext - a text string input. The secret message that you wish to encrypt.

![Encryptor web page text tab showing temperature, precision level, sensor value, and plaintext inputs.](https://cdn-learn.adafruit.com/assets/assets/000/144/082/medium640/temperature___humidity_encryptor_page_text.png?1778080058)

When you press **Encrypt,** a sequence entry text box will appear with an object containing the encrypted message along with metadata required to decrypt and validate it.

Press the **copy** button, along the top right of the box, and then paste the whole thing into the `SEQUENCE` list inside of **code.py** in the user configuration section near the top.

![Text encrypted secret ready to be copied into the sequence list in code.py](https://cdn-learn.adafruit.com/assets/assets/000/144/083/medium640/temperature___humidity_encoded_text.png?1778080996)

```python
SEQUENCE = [
    {
        "type":        "text",
        "data":        "?tH,OledH]BF9zxBSX'LUY^C7390.HFaS[GX",
        "sha256":      "583fd7f36f35c16fb4dc60edf493c74679ce6f26f928bf9995dcae85becf6962",
        "reading":     "lux",
        "precision_level": 100,
    },
    # Add more entries here...
]
```

## Image Secrets
Encrypting image secrets is similar to text. The main differences are:

- Drag and drop an image file on the page instead of entering plaintext into a box. The page supports PNG, JPEG, and BMP formatted images.
- Nonce / IV - required for AES encryption. Leave the default or change it to any 16 character string.
- Max palette colors - how many colors to use for the palette of the resulting Bitmap image. Using the default `256` is fine for most cases.

![Image encryptor page](https://cdn-learn.adafruit.com/assets/assets/000/144/084/medium640/temperature___humidity_encryptor_page_image.png?1778081683)

After you fill in the fields and click **Encrypt & Download** &nbsp;two things will happen. An encrypted copy of the image will be downloaded with a name like **some\_image.abmp.enc** , and the sequence entry box will appear and get populated with an entry for the encoded image.

Press the **copy** button along the top right of the box and then paste the whole thing into the `SEQUENCE` list inside of **code.py** in the user configuration section near the top.

Make sure that the `data` value in the object has the exact name of the downloaded image file. You can change the name to anything, but the name of the file must match the `data` value in this object. Change them both together if you do.

Copy the encoded image file to the **CIRCUITPY** drive.

![Encoded image entry ready to be copied into code.py sequence](https://cdn-learn.adafruit.com/assets/assets/000/144/085/medium640/temperature___humidity_encoded_image.png?1778082178)

```python
SEQUENCE = [
    {
        "type":        "image",
        "data":        "secret_image.abmp.enc",
        "iv":          b"InitializationVe",
        "sha256":      "932185ffbba8b245a97a0819428d6038997e968174cadd3bd0a5bab970d0e560",
        "reading":     "temperature",
        "precision_level": 1,
    },
    # Add more entries here...
]
```

# Sensor-Locked Secrets with CircuitPython

## GPS Coordinates

This version of project code is basically a digital version of a [reverse geo-cache puzzle](https://learn.adafruit.com/reverse-geocache-engagement-box/) like the ones that inspired the project. The key to encrypt secret text or image is derived from GPS coordinates. The secret can only be revealed by taking the device and GPS receiver to the specified location.

## Hardware
### Adafruit Ultimate GPS FeatherWing

[Adafruit Ultimate GPS FeatherWing](https://www.adafruit.com/product/3133)
Give your Feather a sense of place, with an Ultimate GPS FeatherWing. <!--EndFragment-->In 2013 we designed the [Ultimate GPS module](https://www.adafruit.com/products/746) to satisfy all your GPS desires - and now we have brought its power and versatility plus more to our...

In Stock
[Buy Now](https://www.adafruit.com/product/3133)
[Related Guides to the Product](https://learn.adafruit.com/products/3133/guides)
![Angled shot of long, rectangular GPS-enabled add-on board.](https://cdn-shop.adafruit.com/640x480/3133-09.jpg)

### FeatherWing Doubler - Prototyping Add-on For All Feather Boards

[FeatherWing Doubler - Prototyping Add-on For All Feather Boards](https://www.adafruit.com/product/2890)
This is the **FeatherWing Doubler** - a prototyping add-on and more for all Feather boards. This is similar to our [FeatherWing Proto](https://www.adafruit.com/products/2884) except there are two! The magic of the Doubler comes when stacking a Feather and another...

In Stock
[Buy Now](https://www.adafruit.com/product/2890)
[Related Guides to the Product](https://learn.adafruit.com/products/2890/guides)
![Double prototyping feather wing PCB with socket headers installed](https://cdn-shop.adafruit.com/640x480/2890-01.jpg)

Connect the Feather S3 TFT to the GPS Featherwing using a FeatherWing doubler.

![Adafruit Feather ESP32S3 TFT connected to a GPS Featherwing with a FeatherWing doubler. The display shows a successfully revealed secret message.](https://cdn-learn.adafruit.com/assets/assets/000/144/091/medium800/temperature___humidity_gps_secret_revealed.png?1778097066 )

## Encrypt Secrets
[Encryptor Page](https://adafruit.github.io/Sensor_Locked_Secrets_Encryptor/)
To encrypt secrets for GPS coordinate unlocking use, the **Other (custom)** reading type value in the dropdown on the encryptor page. Use **gps** for the custom reading type and enter your coordinates in the key seed string field.

Ensure that your coordinates have the same number of decimal places that the precision level is set to, i.e. **3 decimals** equals **3** precision level.

Also make sure the coordinates are separated by a comma and that there are no spaces around the comma or anywhere else in the string. Example of correct syntax for precision level 3: `40.656,-74.007`

![Encryptor page with "Other" reading type selected and appropriate values filled in to encrypt with GPS coordinates](https://cdn-learn.adafruit.com/assets/assets/000/144/086/medium640/temperature___humidity_encryptor_page_gps.png?1778082767)

## Code

To use the application, you need to obtain **code.py** with the program, and the other project files to place on the Feather **CIRCUITPY** drive.

Thankfully, this can be done in one go. In the example below, click the **Download Project Bundle** button below to download the necessary libraries, the **code.py** file, and other project files in a zip file.

Connect your board to your computer via a known good data+power USB cable. The board should show up in your File Explorer/Finder (depending on your operating system) as a flash drive named **CIRCUITPY**.

Extract the contents of the zip file, copy the **lib** directory files to **CIRCUITPY/lib**. Copy the **code.py** file to your **CIRCUITPY** drive. The program should self start.

https://github.com/adafruit/Adafruit_Learning_System_Guides/blob/main/Sensor_Locked_Secrets/gps/code.py

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

![CIRCUITPY drive screenshot showing required project files and libraries](https://adafruit.github.io/Adafruit_Learning_System_Guides/Sensor_Locked_Secrets_gps.png )

# Sensor-Locked Secrets with CircuitPython

## Lux Level

![Adafruit Feather S3 TFT connected to a MAX44009 lux sensor via STEMMA QT cable. The display shows pixelated noise changing as light shines nearer to the light sensor. Once the lux value reaches 1200 the pixels snap into focus revealing an image of Blinka wrapped around a lock.](https://cdn-learn.adafruit.com/assets/assets/000/144/114/medium800thumb/temperature___humidity_lux_decrypt_image_640.jpg?1778592819 )

This version of the project code uses the MAX44009 light sensor breakout to decrypt secrets with lux value readings.

## Hardware
### Adafruit MAX44009 Wide-range Lux Light Sensor - 188,000 Lux Max

[Adafruit MAX44009 Wide-range Lux Light Sensor - 188,000 Lux Max](https://www.adafruit.com/product/6498)
This is an easy to use&nbsp;lux sensor, and features an ultra-wide 22-bit dynamic range from 0.045  
lux to 188,000 lux. That means you can use the **&nbsp;Adafruit MAX44009 Wide-range Lux Sensor&nbsp;** in darkness or in bright outdoors sun, without having to tweak the...

In Stock
[Buy Now](https://www.adafruit.com/product/6498)
[Related Guides to the Product](https://learn.adafruit.com/products/6498/guides)
![Angled Shot of the Adafruit MAX44009 Wide-range Lux Sensor.](https://cdn-shop.adafruit.com/640x480/6498-00.jpg)

### STEMMA QT / Qwiic JST SH 4-pin Cable - 100mm Long

[STEMMA QT / Qwiic JST SH 4-pin Cable - 100mm Long](https://www.adafruit.com/product/4210)
This 4-wire cable is a little over 100mm / 4" long and fitted with JST-SH female 4-pin connectors on both ends. Compared with the chunkier JST-PH these are 1mm pitch instead of 2mm, but still have a nice latching feel, while being easy to insert and remove.

<a...></a...>

In Stock
[Buy Now](https://www.adafruit.com/product/4210)
[Related Guides to the Product](https://learn.adafruit.com/products/4210/guides)
![Angled shot of STEMMA QT / Qwiic JST SH 4-pin Cable.](https://cdn-shop.adafruit.com/640x480/4210-00.jpg)

Connect the MAX44009 breakout to the Feather S3 TFT with a STEMMA QT cable.

![Adafruit Feather ESP32 S3 TFT connected to a MAX44009 breakout via STEMMA QT cable](https://cdn-learn.adafruit.com/assets/assets/000/144/092/medium640/temperature___humidity_max44009_connected.png?1778592857)

## Encrypt Secrets

Encrypt your secret messages using the process documented on [this guide page](https://learn.adafruit.com/sensor-locked-secrets-with-circuitpython/encrypting-secrets). Choose **lux(lux)** as the reading type. A precision level of `100` or `50` works well for lux readings on the MAX44009.

[Encryptor Page](https://adafruit.github.io/Sensor_Locked_Secrets_Encryptor/)
## Code

To use the application, you need to obtain&nbsp; **code.py** with the program, and the other project files to place on the Feather **CIRCUITPY** drive.

Thankfully, this can be done in one go. In the example below, click the **Download Project Bundle** button below to download the necessary libraries, the **code.py** file, and other project files in a zip file.

Connect your board to your computer via a known good data+power USB cable. The board should show up in your File Explorer/Finder (depending on your operating system) as a flash drive named **CIRCUITPY**.

Extract the contents of the zip file, copy the **lib** directory files to **CIRCUITPY/lib**. Copy the **code.py** file to your **CIRCUITPY** drive. The program should self start.

https://github.com/adafruit/Adafruit_Learning_System_Guides/blob/main/Sensor_Locked_Secrets/max44009/code.py

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

![CIRCUITPY drive screenshot showing required project files and libraries](https://adafruit.github.io/Adafruit_Learning_System_Guides/Sensor_Locked_Secrets_max44009.png )

# Sensor-Locked Secrets with CircuitPython

## Temperature Humidity CO2

![Adafruit Feather ESP32 S3 TFT connected to a STCC4+SHT41 breakout via STEMMA QT. The display shows a successfully revealed secret message](https://cdn-learn.adafruit.com/assets/assets/000/144/094/medium800/temperature___humidity_stcc4_sht41_secret_revealed.png?1778097360 )

This version of the code uses the STCC4+SHT41 breakout to decrypt secrets with temperature, humidity, or CO2 readings. Since all 3 types of data come from the same sensor, it is possible to use a sequence of secrets that are each encrypted with different reading types.

One example usage for this is setting up a scavenger hunt-like experience where participants are encouraged to observe changes to the visible sensor reading and experiment with different ways to influence the sensor or environment to find each secret. The revealed text or image can contain a clue that leads them towards the solution for the next puzzle in the sequence.

## Hardware
### Adafruit STCC4 and SHT41 - CO2, Temperature & Humidity Sensor

[Adafruit STCC4 and SHT41 - CO2, Temperature & Humidity Sensor](https://www.adafruit.com/product/6478)
CO₂&nbsp;sensors are essential for determining if a room is too 'stuffy' - high CO₂ makes humans grumpy and tired. That's why it's always nice to take a deep breath outside where CO₂ is about 400 ppm. However, until now, CO₂ sensors were always really chunky (<a...></a...>

In Stock
[Buy Now](https://www.adafruit.com/product/6478)
[Related Guides to the Product](https://learn.adafruit.com/products/6478/guides)
![Angled shot of CO2, temperature, and humidity sensor breakout.](https://cdn-shop.adafruit.com/640x480/6478-02.jpg)

### STEMMA QT / Qwiic JST SH 4-pin Cable - 100mm Long

[STEMMA QT / Qwiic JST SH 4-pin Cable - 100mm Long](https://www.adafruit.com/product/4210)
This 4-wire cable is a little over 100mm / 4" long and fitted with JST-SH female 4-pin connectors on both ends. Compared with the chunkier JST-PH these are 1mm pitch instead of 2mm, but still have a nice latching feel, while being easy to insert and remove.

<a...></a...>

In Stock
[Buy Now](https://www.adafruit.com/product/4210)
[Related Guides to the Product](https://learn.adafruit.com/products/4210/guides)
![Angled shot of STEMMA QT / Qwiic JST SH 4-pin Cable.](https://cdn-shop.adafruit.com/640x480/4210-00.jpg)

Connect the STCC4+SHT41 breakout to the Feather S3 TFT with a STEMMA QT cable.

![Adafruit Feather ESP32 S3 TFT connected to a STCC4+SHT41 breakout via STEMMA QT cable](https://cdn-learn.adafruit.com/assets/assets/000/144/093/medium800/temperature___humidity_stcc4_sht41_connected.png?1778097310 )

## Encrypt Secrets

Encrypt your secret messages using the process documented on [this guide page](https://learn.adafruit.com/sensor-locked-secrets-with-circuitpython/encrypting-secrets). Choose **temperature** ,&nbsp; **humidity** , or **CO2** as desired for each secret that you encrypt. Temperature and humidity readings use Celsius and percentage units respectively. Both work well with a precision level of&nbsp;`1`, but you can use a larger value if you want make the target range easier to find. CO2 uses PPM which is likely to have a value in the range of 300-1000 for normal environments, so a larger precision level of `100` or `50` works better for it.

Danger: It is unhealthy for humans to spend time in environments with CO2 level over 1000ppm. A base line reading in clean outdoor air is typically around 400. CO2 based encryption should use a target level of 1000 or less so that it does not encourage participants to create or venture into unsafe environments.

[Encryptor Page](https://adafruit.github.io/Sensor_Locked_Secrets_Encryptor/)
## Code

To use the application, you need to obtain&nbsp; **code.py** with the program, and the other project files to place on the Feather **CIRCUITPY** drive.

Thankfully, this can be done in one go. In the example below, click the **Download Project Bundle** button below to download the necessary libraries, the **code.py** file, and other project files in a zip file.

Connect your board to your computer via a known good data+power USB cable. The board should show up in your File Explorer/Finder (depending on your operating system) as a flash drive named **CIRCUITPY**.

Extract the contents of the zip file, copy the **lib** directory files to **CIRCUITPY/lib**. Copy the **code.py** file to your **CIRCUITPY** drive. The program should self start.

https://github.com/adafruit/Adafruit_Learning_System_Guides/blob/main/Sensor_Locked_Secrets/stcc4_sht41/code.py

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

![CIRCUITPY drive screenshot showing required project files and libraries](https://adafruit.github.io/Adafruit_Learning_System_Guides/Sensor_Locked_Secrets_stcc4_sht41.png )

# Sensor-Locked Secrets with CircuitPython

## Using Other Sensors

The preceding pages cover versions of the project for the MAX44009, STCC4+SHT41, and GPS Featherwing. If you have a different light sensor, temperature/humidity sensor, or supported GPS receiver, the code can be easily adapted by changing the driver import and sensor initialization. Since all of the Adafruit libraries for the same type of sensors share common property names for their data readings, they are largely interchangeable in these projects. For different GPS breakouts, be sure to update the pins used for initialization according to the module you have.

For example, the following illustrates changing the lux version of the project to use the VCNL4030.

### Existing code:
```python
from adafruit_max44009 import MAX44009

# ...

# =============================================================================
# SENSOR SETUP
# =============================================================================

i2c = board.I2C()
sensor = MAX44009(i2c)
```

### VCNL4030 Adaptation:
```python
from adafruit_vcnl4030 import VCNL4030

# ...

# =============================================================================
# SENSOR SETUP
# =============================================================================

i2c = board.I2C()
sensor = VCNL4030(i2c)
```

## Different Types of Sensors

If you want to venture outside the realm of GPS, lux, temperature, humidity, and CO2, the code can be adapted for other sensor types, but it requires a little more work.

The following sections illustrate changes needed to use a TMAG5273 magnetic sensor.

Change the import and initialization of the driver to use the one for the new sensor.

```python
import adafruit_tmag5273

# ...

sensor = adafruit_tmag5273.TMAG5273(i2c)
```

Add suitable entries to the `READING_TYPES` dictionary for the new sensor. The magnetic sensor has the property `magnetic` that returns x, y, and z values in a tuple. The attribute name entry in this dictionary is changed from string to tuple so that it can hold a name and a sub-index.

If your sensor has a basic property that returns a single value, then just use a string with the property name like the original project code does.

```python
READING_TYPES = {
    # type key  :  attr info      , unit  string
    "magnetic_x": (("magnetic", 0), "uT"),
    "magnetic_y": (("magnetic", 1), "uT"),
    "magnetic_z": (("magnetic", 2), "uT"),
}
```

Update the code inside the `get_range_string_from_sensor()` function to handle the attribute name/sub-indexing scheme.

```python
attr_info, _unit = READING_TYPES[_entry["reading"]]
attr_name, subindex = attr_info

reading = int(getattr(sensor, attr_name)[subindex])
```

Use one of the reading type key values `magnetic_x`, `magnetic_y`, or `magnetic_z` as the value for a custom reading type on the encryptor page.

[Encryptor Page](https://adafruit.github.io/Sensor_Locked_Secrets_Encryptor/)
![Encryptor page showing magnetic_x reading type used to encrypt a secret text message](https://cdn-learn.adafruit.com/assets/assets/000/144/087/medium800/temperature___humidity_magnetic_x.png?1778089846 )


## Featured Products

### 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)
### Adafruit Ultimate GPS FeatherWing

[Adafruit Ultimate GPS FeatherWing](https://www.adafruit.com/product/3133)
Give your Feather a sense of place, with an Ultimate GPS FeatherWing. <!--EndFragment-->In 2013 we designed the [Ultimate GPS module](https://www.adafruit.com/products/746) to satisfy all your GPS desires - and now we have brought its power and versatility plus more to our...

In Stock
[Buy Now](https://www.adafruit.com/product/3133)
[Related Guides to the Product](https://learn.adafruit.com/products/3133/guides)
### Adafruit MAX44009 Wide-range Lux Light Sensor - 188,000 Lux Max

[Adafruit MAX44009 Wide-range Lux Light Sensor - 188,000 Lux Max](https://www.adafruit.com/product/6498)
This is an easy to use&nbsp;lux sensor, and features an ultra-wide 22-bit dynamic range from 0.045  
lux to 188,000 lux. That means you can use the **&nbsp;Adafruit MAX44009 Wide-range Lux Sensor&nbsp;** in darkness or in bright outdoors sun, without having to tweak the...

In Stock
[Buy Now](https://www.adafruit.com/product/6498)
[Related Guides to the Product](https://learn.adafruit.com/products/6498/guides)
### Adafruit STCC4 and SHT41 - CO2, Temperature & Humidity Sensor

[Adafruit STCC4 and SHT41 - CO2, Temperature & Humidity Sensor](https://www.adafruit.com/product/6478)
CO₂&nbsp;sensors are essential for determining if a room is too 'stuffy' - high CO₂ makes humans grumpy and tired. That's why it's always nice to take a deep breath outside where CO₂ is about 400 ppm. However, until now, CO₂ sensors were always really chunky (<a...></a...>

In Stock
[Buy Now](https://www.adafruit.com/product/6478)
[Related Guides to the Product](https://learn.adafruit.com/products/6478/guides)
### FeatherWing Doubler - Prototyping Add-on For All Feather Boards

[FeatherWing Doubler - Prototyping Add-on For All Feather Boards](https://www.adafruit.com/product/2890)
This is the **FeatherWing Doubler** - a prototyping add-on and more for all Feather boards. This is similar to our [FeatherWing Proto](https://www.adafruit.com/products/2884) except there are two! The magic of the Doubler comes when stacking a Feather and another...

In Stock
[Buy Now](https://www.adafruit.com/product/2890)
[Related Guides to the Product](https://learn.adafruit.com/products/2890/guides)
### USB Type A to Type C Cable - 1ft - 0.3 meter

[USB Type A to Type C Cable - 1ft - 0.3 meter](https://www.adafruit.com/product/4473)
As technology changes and adapts, so does Adafruit. This&nbsp;&nbsp; **USB Type A to Type C** cable will help you with the transition to USB C, even if you're still totin' around a USB Type A hub, computer or laptop.

USB C is the latest industry-standard connector for...

In Stock
[Buy Now](https://www.adafruit.com/product/4473)
[Related Guides to the Product](https://learn.adafruit.com/products/4473/guides)

## Related Guides

- [Adafruit ESP32-S3 TFT Feather](https://learn.adafruit.com/adafruit-esp32-s3-tft-feather.md)
- [Adafruit STCC4 and SHT41 CO2, Temperature & Humidity Sensor](https://learn.adafruit.com/adafruit-stcc4-and-sht41-co2-temperature-humidity-sensor.md)
- [Adafruit MAX44009 Lux Light Sensor](https://learn.adafruit.com/adafruit-max44009-lux-light-sensor.md)
- [Easy Alexa (Echo) Control of your ESP8266 Huzzah](https://learn.adafruit.com/easy-alexa-or-echo-control-of-your-esp8266-huzzah.md)
- [Multi-Sensor IoT Environmental Sensor Box With CircuitPython](https://learn.adafruit.com/remote-iot-environmental-sensor.md)
- [4x4 Rotary Encoder MIDI Messenger](https://learn.adafruit.com/4x4-rotary-encoder-midi-messenger.md)
- [Glitter Positioning System](https://learn.adafruit.com/glitter-positioning-system.md)
- [Bluefruit LE Feather Robot Rover](https://learn.adafruit.com/bluefruit-feather-robot.md)
- [Touch Tone Phone Dial-a-Song](https://learn.adafruit.com/touch-tone-phone-dial-a-song.md)
- [USB Host to BLE Keyboard Adapter](https://learn.adafruit.com/esp32-s3-usb-to-ble-keyboard-adapter.md)
- [Walkmp3rson: Personal MP3 'Tape' Player](https://learn.adafruit.com/walkmp3rson-personal-mp3-tape-player.md)
- [Talking Musical NeoPixel Clock with Infrared, BLE and Touch Controls](https://learn.adafruit.com/talking-musical-neo-pixel-clock-with-infrared-ble-and-touch-controls.md)
- [Integrating Color Sensors with itsaSNAP and HomeKit](https://learn.adafruit.com/integrating-color-sensors-with-itsasnap-and-homekit.md)
- [Nunchuck Controlled Laser Cat Toy](https://learn.adafruit.com/nunchuck-controlled-laser-cat-toy.md)
- [CircuitPython Web Workflow Code Editor Quick Start](https://learn.adafruit.com/getting-started-with-web-workflow-using-the-code-editor.md)
- [MIDI Melody Maker](https://learn.adafruit.com/midi-melody-maker.md)
- [GPS Tour Guide](https://learn.adafruit.com/gps-tour-guide.md)
