# CircuitPython TFT Candy Hearts

## Overview

![](https://cdn-learn.adafruit.com/assets/assets/000/088/270/medium800/adabox_main_banner.jpg?1581291456)

This guide turns a [TFT Gizmo](https://www.adafruit.com/product/4367) into a conversation heart, just like those chalky candies that show up around Valentines. The code is written in [CircuitPython](https://learn.adafruit.com/welcome-to-circuitpython) and can run on the [Circuit Playground Bluefruit](http://www.adafruit.com/product/4333). If you bought an [AdaBox014](https://learn.adafruit.com/adabox014), then you have everything you need. Or you can get the items from the links below.

Two versions of the code are provided. The first is a simple one that will let you set predefined messages and colors and then cycle through them by pressing the buttons on the Circuit Playground. The second one uses the Bluetooth Low Energy (BLE) feature of the Circuit Playground along with the [Adafruit Bluefruit LE Connect app](https://learn.adafruit.com/bluefruit-le-connect) to allow you to set message and colors from your BLE enabled smart phone or tablet.

## Parts
### Circuit Playground Bluefruit - Bluetooth® Low Energy

[Circuit Playground Bluefruit - Bluetooth® Low Energy](https://www.adafruit.com/product/4333)
 **Circuit Playground Bluefruit** is our third board in the Circuit Playground series, another step towards a perfect introduction to electronics and programming. We've taken the popular Circuit Playground Express and made it even better! Now the main chip is an nRF52840...

Out of Stock
[Buy Now](https://www.adafruit.com/product/4333)
[Related Guides to the Product](https://learn.adafruit.com/products/4333/guides)
![shot of a Black woman's neon-green manicured hand holding up a Circuit Playground Bluefruit glowing rainbow LEDs.](https://cdn-shop.adafruit.com/640x480/4333-11.jpg)

### Circuit Playground TFT Gizmo - Bolt-on Display + Audio Amplifier

[Circuit Playground TFT Gizmo - Bolt-on Display + Audio Amplifier](https://www.adafruit.com/product/4367)
Extend and expand your Circuit Playground projects with a bolt on TFT Gizmo that lets you add a lovely color display in a sturdy and reliable fashion. This PCB looks just like a round TFT breakout but has permanently affixed M3 standoffs that act as mechanical and electrical...

In Stock
[Buy Now](https://www.adafruit.com/product/4367)
[Related Guides to the Product](https://learn.adafruit.com/products/4367/guides)
![Hand pressing buttons on circuit playground, then turning over to show TFT gizmo display an image of a friendly robot or snake](https://cdn-shop.adafruit.com/product-videos/640x480/4367-05.jpg)

### Adafruit Circuit Playground Bluefruit Express Starter Kit

[Adafruit Circuit Playground Bluefruit Express Starter Kit](https://www.adafruit.com/product/4504)
If you missed out on ADABOX 014, its not too late for you to pick up the parts necessary to build many of the projects! This kit pack doesn't come with tissue paper or the nifty extras, but it does have all the electronic goodies you need  
  
This project pack features...

Out of Stock
[Buy Now](https://www.adafruit.com/product/4504)
[Related Guides to the Product](https://learn.adafruit.com/products/4504/guides)
![Top Down Front Kit Shot of the Adafruit Circuit Playground Bluefruit Express Starter Kit.](https://cdn-shop.adafruit.com/640x480/4504-07.jpg)

# CircuitPython TFT Candy Hearts

## CircuitPython on Circuit Playground Bluefruit

# Install or Update CircuitPython

Follow this quick step-by-step to install or update CircuitPython on your Circuit Playground Bluefruit.

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

Download and save it to your Desktop (or wherever is handy)

![adafruit_products_CPB_Download_UF2.png](https://cdn-learn.adafruit.com/assets/assets/000/080/530/medium640/adafruit_products_CPB_Download_UF2.png?1567715178)

Plug your Circuit Playground Bluefruit into your computer using a known-good data-capable USB cable.

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

Double-click the small **Reset** button in the middle of the CPB (indicated by the red arrow in the image). The ten NeoPixel LEDs will all turn red, and then will all turn green. If they turn all red and stay red, check the USB cable, try another USB port, etc. The little red LED next to the USB connector will pulse red - this is ok!

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

(If double-clicking doesn't do it, try a single-click!)

![adafruit_products_CPB_Front_Reset_Button_Arrow.jpg](https://cdn-learn.adafruit.com/assets/assets/000/080/532/medium640/adafruit_products_CPB_Front_Reset_Button_Arrow.jpg?1567715535)

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

 

 

 

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

![adafruit_products_CPB_CPLAYBTBOOT.png](https://cdn-learn.adafruit.com/assets/assets/000/080/533/medium640/adafruit_products_CPB_CPLAYBTBOOT.png?1567715858)

![adafruit_products_CBP_drag_UF2.png](https://cdn-learn.adafruit.com/assets/assets/000/080/534/medium640/adafruit_products_CBP_drag_UF2.png?1567715871)

The LEDs will turn red. Then, the **CPLAYBTBOOT** drive will disappear and a new disk drive called **CIRCUITPY** will appear.

That's it, you're done! :)

![adafruit_products_CBP_CIRCUITPY.png](https://cdn-learn.adafruit.com/assets/assets/000/080/535/medium640/adafruit_products_CBP_CIRCUITPY.png?1567716034)

# CircuitPython TFT Candy Hearts

## Basic Code

This is the basic version of the code. You set predefined message text and heart colors. Then, you can cycle through them using either of the buttons on the Circuit Playground Bluefruit.

Connect your Circuit Playground Bluefruit to your computer via a known good data USB cable. The board should show up in your operating system file explorer/finder as a flash drive named **CIRCUITPY**. Time to copy over some files for this project.

## Libraries

First, make sure you have these libraries copied over to the board [following this guide page](https://learn.adafruit.com/adafruit-circuit-playground-bluefruit/circuit-playground-bluefruit-circuitpython-libraries):

![](https://cdn-learn.adafruit.com/assets/assets/000/088/114/medium800/adabox_libraries.png?1580935783)

Info: 

## Code

Here's the code for the basic version. We'll go in to more detail about how it works in the following pages.

This code uses a custom font file and a BMP file for the heart image. To get those as well as the code, click the **Project Zip** link in the embedded code listing below. This will download all the files you need at once.

In addition to the code, be sure to copy the **Multicolore\_36.bdf** and **heart\_bw.bmp** file to you **CIRCUITPY** folder.

https://github.com/adafruit/Adafruit_Learning_System_Guides/blob/main/TFT_Gizmo_Candy_Hearts/candy_hearts/code.py

Primary: 

# CircuitPython TFT Candy Hearts

## Customizing

You can customize the messages and the colors if you want. All the lines of code to do this are at the top.

## Changing Messages

The messages are stored as a tuple of tuples. Yah, that sounds weird, but tuples can contain anything, including other tuples. It's these lines of code at the top:

```python
HEART_MESSAGES = (
    ("I LUV", "YOU"),
    ("SAY", "YES"),
    ("HUG", "ME"),
    ("BE", "MINE"),
    ("TEXT","ME"),
    ("OMG","LOL"),
    ("PEACE",""),
)
```

Each message is a tuple with two text strings - one for each line. You need to specify both, even if you only want one line. See the **PEACE** message as an example of a single line message. Its second line is blank. You can remove or add more messages as you wish or edit the ones that are there.

**NOTE:** Line 1 can have up to 9 characters. Line 2 can have up to 5 characters.

Info: 

## Changing Colors

You can also change the heart and message text colors if you want. These are also defined as tuples, but this time just a straight simple tuple of color values. It's these lines of code at the top:

```python
HEART_COLORS = (
    0xEAFF50, # yellow
    0xFFAD50, # orange
    0x9D50FF, # purple
    0x13B0FE, # blue
    0xABFF96, # green
    0xFF96FF, # pink
)
MESSAGE_COLORS = (
    0xFF0000, # red
)
```

There's a separate tuple for the heart colors, `HEART_COLORS`, and one for the message colors, `MESSAGE_COLORS`. Just add/remove entries as you wish. We kept `MESSAGE_COLORS` to a single value in the default code just because it seemed to look the best. But you can add more if you want.

## Changing Interaction

The default code changes messages whenever either of the buttons on the Circuit Playground are pressed. That's done with these lines of code:

```python
# wait for button press
while not cp.button_a and not cp.button_b:
    pass
# just a little debounce
time.sleep(0.25)
```

You could change that to something else if you want. You would replace those lines with something else. Some ideas are **tap** :

```python
# wait for tap
while not cp.tapped:
    pass
```

 **shake** :

```python
# wait for shake
while not cp.shake():
    pass
```

or a simple **timer** :

```python
# change every 5 seconds
time.sleep(5)
```

But you could also maybe do sound? Or temperature?

# CircuitPython TFT Candy Hearts

## How It Works

This code isn't very complex. However, there a few things it does that are worth discussing so you can use the same ideas in your code and projects.

## Custom Font

To get the TFT candy heart to look like an actual candy heart, a custom font is used. There's a guide about this here:

[Custom Fonts for CircuitPython Displays](https://learn.adafruit.com/custom-fonts-for-pyportal-circuitpython-display/overview)
The font used for the TFT Candy Hearts is this one:

[Multicolore font from dafont](https://www.dafont.com/multicolore.font)
which we've already converted for use with CircuitPython and this project. The font file will be included along with the code when you download the Project Zip. See the Code pages for details about downloading it and copying it to your board.

## Text Positioning

Thanks to a [recent update](https://github.com/adafruit/Adafruit_CircuitPython_Display_Text/releases/tag/2.2.0) to the [CircuitPython Display Text](https://github.com/adafruit/Adafruit_CircuitPython_Display_Text) library, you can now change the anchor point used to locate the text label. You do so by using the `anchor_point` property of the `label` and giving it an `(x, y)` tuple, like this:

```python
label.anchor_point = (0.1, 0.8)
```

The values range from 0 to 1 with `x` being the horizontal and `y` being the vertical. The origin is in the upper left corner. A value of 0 is at the origin. A value of 1 is all the way to the right/down.

Here are some example locations:

![](https://cdn-learn.adafruit.com/assets/assets/000/099/777/medium800/adabox_text_bound.png?1614363575)

You can then set the position of the label on the display using the `anchored_position` property and also specifying an `(x, y)` tuple. But this time, the values are actual screen coordinates in pixels, like this:

```python
label.anchored_position = (120, 85)
```

The candy hearts code uses two labels, one for each line of text. The `x` position is simply half the screen width, 240 / 2 = 120, so that it is centered. The `y` positions were determined by trial and error. Just came up with values that looked about right.

The end result is something like this:

![](https://cdn-learn.adafruit.com/assets/assets/000/088/116/medium800/adabox_heart_labels.png?1580936428)

If you want to tweak the position of the messages, you can change these lines of code:

```python
# update location for new text bounds
line1.anchored_position = (120, 85)
line2.anchored_position = (120, 175)
```

## Changing Heart Color

The way the heart color is changed is kind of interesting. Instead of having separate bitmap files for each color, the palette is altered directly. For a review of how `bitmaps` and `palettes` work in CircuitPython displayio, see here:

[Bitmap and Palette in displayio](https://learn.adafruit.com/circuitpython-display-support-using-displayio/bitmap-and-palette)
But for quick reference, we copy the important illustration here:

![](https://cdn-learn.adafruit.com/assets/assets/000/088/117/medium800/adabox_circuitpython_bitmap_palette.png?1580936937)

It is the `palette` that defines the colors that are used to render the `bitmap` on the screen. And you can change any of the palette entries anytime you want by doing something like:

```python
palette[1] = 0x0000FF # blue
```

This would set the second entry (index 1) of the palette to the color blue. Any pixel of the bitmap using that palette entry would then get rendered as blue. But then you can do:

```python
palette[1] = 0x00FF00 # green
```

and those same pixels would now become green.

This trick is used for the heart. The actual bitmap is only two colors - black and white:

![](https://cdn-learn.adafruit.com/assets/assets/000/088/118/medium800/adabox_heart_no_labels.png?1580937395)

The black pixels are left alone so the background is always black. But you could change that if you want. The candy heart code only changes the white entry of the bitmap. The actual colors are defined by you at the top of the code. The `choice` function from the `random` library is used to select one of these at random. And then the palette entry for white is set to it:

```python
palette[1] = choice(HEART_COLORS)
```

Then whatever used to be white becomes the new color. And when it happens again, the color is replaced by a new random color. And so on.

# CircuitPython TFT Candy Hearts

## BLE Code

How about a version that works over Bluetooth? You know, so you could like control it from your phone? Sure, we can do that. Here's a version of the code that let's you use the [Adafruit Bluefruit LE Connect App](https://learn.adafruit.com/bluefruit-le-connect) to send text and color. Now, instead of pre-defined messages and colors, you can use the [BLE Connect App](https://learn.adafruit.com/bluefruit-le-connect) to send them.

## Libraries

First, make sure you have these libraries copied over to the **/lib** directory on the board's **CIRCUITPY** drive [following this guide page](https://learn.adafruit.com/adafruit-circuit-playground-bluefruit/circuit-playground-bluefruit-circuitpython-libraries):

![](https://cdn-learn.adafruit.com/assets/assets/000/088/233/medium800/adabox_libraries_ble.png?1581266113)

Info: 

## Code

Here's the BLE version of the code. We'll talk about how to interact with it next.

This code uses a custom font file and a BMP file for the heart image. To get those as well as the code, click the **Project Zip** link in the embedded code listing below. This will download all the files you need at once.

In addition to the code, be sure to copy the **Multicolore\_36.bdf** and **heart\_bw.bmp** file to you **CIRCUITPY** folder.

https://github.com/adafruit/Adafruit_Learning_System_Guides/blob/main/TFT_Gizmo_Candy_Hearts/candy_heart_ble/code.py

Primary: 

## Bonus CLUE Versions

The [Adafruit CLUE](https://www.adafruit.com/product/4500) uses the same TFT display as the Gizmo. This makes it pretty easy to adapt the code for use on the CLUE. You'll find CLUE versions of the code in the project zip. Looks for the two files that names start with **clue**.

# CircuitPython TFT Candy Hearts

## Using BLE Connect App

## Connect

To make the initial connection, launch the [BLE Connect App](https://learn.adafruit.com/bluefruit-le-connect), and then:

Look for the device named **Candy Heart** and click **CONNECT**.

![adabox_ble_connect1.png](https://cdn-learn.adafruit.com/assets/assets/000/088/280/medium640/adabox_ble_connect1.png?1581292892)

## Change Text

To change the heart text message, follow these steps.

Select the **UART** option in the modules list.

![adabox_ble_connect2.png](https://cdn-learn.adafruit.com/assets/assets/000/088/281/medium640/adabox_ble_connect2.png?1581292952)

Type in the text you want for the message and click **SEND**.

**NOTE** : Use a comma to separate the two lines of text, ex: `line1,line2`

![adabox_ble_connect3.png](https://cdn-learn.adafruit.com/assets/assets/000/088/282/medium640/adabox_ble_connect3.png?1581293001)

The text will be sent.

![adabox_ble_connect4.png](https://cdn-learn.adafruit.com/assets/assets/000/088/287/medium640/adabox_ble_connect4.png?1581293340)

And the heart message will be updated.

![adabox_heart_update1.jpg](https://cdn-learn.adafruit.com/assets/assets/000/088/288/medium640/adabox_heart_update1.jpg?1581293363)

## Change Color

To change the heart color, follow these steps.

Select the **Controller** option in the modules list.

![adabox_ble_connect7.png](https://cdn-learn.adafruit.com/assets/assets/000/088/284/medium640/adabox_ble_connect7.png?1581293180)

Click the **Color Picker** option.

![adabox_ble_connect5.png](https://cdn-learn.adafruit.com/assets/assets/000/088/283/medium640/adabox_ble_connect5.png?1581293130)

Select the color you want and hit **SELECT**.

![adabox_ble_connect6.png](https://cdn-learn.adafruit.com/assets/assets/000/088/285/medium640/adabox_ble_connect6.png?1581293276)

And the heart color will be updated.

![adabox_heart_update2.jpg](https://cdn-learn.adafruit.com/assets/assets/000/088/289/medium640/adabox_heart_update2.jpg?1581293397)


## Featured Products

### Circuit Playground Bluefruit - Bluetooth® Low Energy

[Circuit Playground Bluefruit - Bluetooth® Low Energy](https://www.adafruit.com/product/4333)
 **Circuit Playground Bluefruit** is our third board in the Circuit Playground series, another step towards a perfect introduction to electronics and programming. We've taken the popular Circuit Playground Express and made it even better! Now the main chip is an nRF52840...

Out of Stock
[Buy Now](https://www.adafruit.com/product/4333)
[Related Guides to the Product](https://learn.adafruit.com/products/4333/guides)
### Circuit Playground TFT Gizmo - Bolt-on Display + Audio Amplifier

[Circuit Playground TFT Gizmo - Bolt-on Display + Audio Amplifier](https://www.adafruit.com/product/4367)
Extend and expand your Circuit Playground projects with a bolt on TFT Gizmo that lets you add a lovely color display in a sturdy and reliable fashion. This PCB looks just like a round TFT breakout but has permanently affixed M3 standoffs that act as mechanical and electrical...

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

## Related Guides

- [Adafruit Circuit Playground Bluefruit](https://learn.adafruit.com/adafruit-circuit-playground-bluefruit.md)
- [Adafruit Circuit Playground TFT Gizmo](https://learn.adafruit.com/adafruit-tft-gizmo.md)
- [Getting Started with CircuitPython and Bluetooth Low Energy](https://learn.adafruit.com/circuitpython-nrf52840.md)
- [LED Reactive Light-Up Hockey Puck in MakeCode](https://learn.adafruit.com/led-hockey-puck.md)
- [Circuit Playground TFT Gizmo Dreidel](https://learn.adafruit.com/circuit-playground-tft-gizmo-dreidel.md)
- [Wireless Image Transfer with Circuit Playground Bluefruit and TFT Gizmo](https://learn.adafruit.com/wireless-image-transfer-with-circuit-playground-bluetooth-and-tft-gizmo.md)
- [PyLeap WAV Playback for Circuit Playground Bluefruit](https://learn.adafruit.com/pyleap-wav-playback-for-cpb.md)
- [Wireless Image Transfer with Circuit Playground Bluefruit and E-Ink Gizmo](https://learn.adafruit.com/wireless-image-transfer-with-circuit-playground-bluetooth-and-eink-gizmo.md)
- [Bluetooth TV Zapper](https://learn.adafruit.com/bluetooth-tv-zapper.md)
- [No-Solder LED Disco Tie with Bluetooth](https://learn.adafruit.com/no-solder-circuit-playground-bluetooth-disco-tie.md)
- [PyLeap Button Controlled NeoPixels for Circuit Playground Bluefruit](https://learn.adafruit.com/pyleap-buttons-neopixels.md)
- [TensorFlow Lite for Circuit Playground Bluefruit Quickstart](https://learn.adafruit.com/tensorflow-lite-for-circuit-playground-bluefruit-quickstart.md)
- [File Glider](https://learn.adafruit.com/file-glider.md)
- [How to use the Puppet Module in the Bluefruit Playground App](https://learn.adafruit.com/how-to-use-the-puppet-module-in-the-bluefruit-playground-app.md)
- [Bluefruit LE Connect for iOS and Android](https://learn.adafruit.com/bluefruit-le-connect.md)
- [CircuitPython BLE Libraries on Any Computer](https://learn.adafruit.com/circuitpython-ble-libraries-on-any-computer.md)
- [CircusPython: Jump through Hoops with CircuitPython Bluetooth LE](https://learn.adafruit.com/circuspython-jump-through-hoops-with-bluetooth-le.md)