# Turtle Graphics in CircuitPython on TFT Gizmo
## Overview
https://youtu.be/Yy3T2r5h6-o
Learn to create your own graphics programs with Turtle Graphics on the Circuit Playground Bluefruit!
The legendary Turtle graphics of the Logo programming language has made their way to CircuitPython! Now, you can learn to program your own graphics right on the TFT Gizmo screen attached to a Circuit Playground Bluefruit board!
In this guide, we'll look at some general Turtle commands, then we'll set up the Circuit Playground Bluefruit and TFT Gizmo to use Turtle in CircuitPython, and then we'll run some example programs to draw sweet graphics on the display!
Primary:
You may have heard of, or even played around with, [_turtle graphics_](https://en.wikipedia.org/wiki/Turtle_graphics). Simply put, this is a metaphor for drawing vector images where you control a _turtle _that can drag a pen along with it. Commands to the turtle include things like move forward some distance, turn left or right by some angle, lift the pen off the paper (so that moving won't make a mark), or put it on the paper (so that moving will make a mark).
There have been many on-screen implementations of turtle graphics, most notably the [LOGO](https://en.wikipedia.org/wiki/Logo_(programming_language)) programming language. Versions have also been made that control a robot that has a pen so as to create on-paper copies of turtle drawings.
## Parts
Featured
### 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...
In Stock
[Buy Now](https://www.adafruit.com/product/4333)
[Related Guides to the Product](https://learn.adafruit.com/products/4333/guides)
Featured
### 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)
Featured
### Fully Reversible Pink/Purple USB A to micro B Cable - 1m long
[Fully Reversible Pink/Purple USB A to micro B Cable - 1m long](https://www.adafruit.com/product/4111)
This cable is not only super-fashionable, with a woven pink and purple Blinka-like pattern, it's also fully reversible! That's right, you will save _seconds_ a day by not having to flip the cable around.
First let's talk about the cover and over-molding. We got these...
In Stock
[Buy Now](https://www.adafruit.com/product/4111)
[Related Guides to the Product](https://learn.adafruit.com/products/4111/guides)
Featured
### Lithium Ion Polymer Battery with Short Cable - 3.7V 350mAh
[Lithium Ion Polymer Battery with Short Cable - 3.7V 350mAh](https://www.adafruit.com/product/4237)
Lithium-ion polymer (also known as 'lipo' or 'lipoly') batteries are thin, light, and powerful. The output ranges from 4.2V when completely charged to 3.7V. This battery has a capacity of 350mAh for a total of about 1.3 Wh. If you need a larger (or smaller!) battery,
In Stock
[Buy Now](https://www.adafruit.com/product/4237)
[Related Guides to the Product](https://learn.adafruit.com/products/4237/guides)
# Turtle Graphics in CircuitPython on TFT Gizmo
## The Turtle API
## Controlling the Pen
**`pendown()`**
Lower the pen, causing subsequent commands will draw.
Aliases: **`pd()`**, **`down()`**
**`penup()`**
Raise the pen, causing subsequent commands to not draw.
Alaises: **`pu()`**, **`up()`**
`pencolor(color=None)`
The form without an argument will return the current pen color as a 24-bit integer. The other form sets the pen color to the specified value. The Color class should be used for this value: `WHITE`, `BLACK`, `RED`, `ORANGE`, `YELLOW`, `GREEN`, `BLUE`, `PURPLE`, `PINK`.
E.g. `turtle.pencolor(adafruit_turtle.Color.RED)`
## Moving
**`forward(distance)`**
Move the turtle forward (on its current heading) by the specified distance. The distance is a number of pixels if the turtle is moving exactly vertically or horizontally.
Alias: **`fd`**
**`backward(distance)`**
Move the turtle backward (opposite its current heading) by the specified distance. The distance is a number of pixels if the turtle is moving exactly vertically or horizontally.
Aliases: **`bk`** , **`back`**
**`setx(x)`**
Set the turtle's horizontal coordinate.
**`sety(y)`**
Set the turtle's vertical coordinate.
**`goto(x, y)`**
Set both coordinates of the turtle.
## Heading
Drawing in a straight line isn't that interesting, so the direction that the turtle is facing (and thus moving) can be changed. This is called its _heading_. The first two functions below set what it means to change the heading by some value. The result of calling these methods stay in effect until the next call to one of them. By default, degrees are used, with a change of 1 corresponding to 1 degree.
**`degrees(fullcircle=360)`**
A full circle is 360 degrees and, by default, changing the heading by 1 means changing it by one degree. Supplying a different value will serve to scale those incremental heading changes. For example, if you call `degrees(180)`, changing the heading by 1 will change it by 2 degrees.
**`radians()`**
Use radians to turn the turtle. Changing the heading by 1 now means changing it by 1 radian (about 57.3 degrees).
The remaining methods change the turtle's heading.
**`left(angle)`**
Turn the turtle left by _angle_ (what that means is subject to the above methods).
Alias: **`lt`**
**`right(angle)`**
Turn the turtle right by _angle_ (what that means is subject to the above methods).
Alias: **`rt`**
**`setheading(angle)`**
Set the heading of the turtle to _angle_. Up is an _angle_ of 0, right is 90.
Alias: **`seth`**
## Shapes
**`dot(radius=None, color=None)`**
Draw a filled-in circle centered on the turtle's current position. Turtle position and heading are unchanged.
If _radius_ is omitted a reasonable one is used, otherwise _radius_ is used as the radius of the dot. If _color_ is omitted the current pen color is used, otherwise _color_ is used. This does not change the pen's color. As above, colors are available from the `Color` class.
**`circle(radius, extent=None, steps=None)`**
Draw a unfilled circle using the turtle's current pen color. This uses a computed sequence of calls to `forward` and `left` so the turtle's position and heading are changed. Since the circle drawing uses `left`, it draws counterclockwise by default. If _radius_ is negative (i.e. \< 0) drawing is done clockwise.
The radius of the desired circle is specified by _radius_, which is a number of pixels from the center to the edge.
The argument _extent_ specifies what portion of the circle to draw and is specified in the same units as calls to `left` and `right`, as determined by the most recent call to `degrees` or `radians`. The default is to draw the complete circle. Calling `circle(10, extent=180)` will draw half a circle of radius 10, assuming that `radians` hasn't been called and neither has `degrees` with an argument other than 360. The turtle's heading is always what it was after drawing the last part of the circle, regardless _extent_. This will always be at the tangent to the circle. You can use this in your drawings. E.g. to draw a closed half-circle:
```auto
turtle.circle(20, extent=180)
turtle.left(90)
turtle.forward(40)
```
The final argument, _steps_, determines how many sides the circle has. By default (_steps_ is `None`) as many are used as required to create a smooth circle. Specifying a value for _steps_ has the effect of drawing that many line segments instead. So circle(radius r, steps=6) will draw a hexagon.
If you draw a full circle, the turtle will end up back where it started with the heading it started with. By drawing circles (of other polygons by using _steps_) repeatedly and turning between each, some interesting designs can be created.
```auto
for _ in range(36):
turtle.circle(50, steps=6)
turtle.left(10)
```
## More control
**`home()`**
Move the turtle to its initial position and heading.
**`clear()`**
Clear the screen, the position and heading of the turtle is unaffected.
## Queries
These methods let you ask the turtle about aspects of it's current state.
**`pos()`**
Returns the turtle's (x, y) position.
**`xcor()`**
Returns the turtle's x coordinate.
**`ycor()`**
Returns the turtle's y coordinate.
**`heading()`**
Returns the turtle's heading.
**`isdown()`**
Returns whether the pen is down (i.e. drawing).
# Turtle Graphics in CircuitPython on TFT Gizmo
## 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)
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!)
You will see a new disk drive appear called **CPLAYBTBOOT**.
Drag the **adafruit\_circuitpython\_etc.uf2** file to **CPLAYBTBOOT.**
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! :)
# Turtle Graphics in CircuitPython on TFT Gizmo
## Assembly
Info:
Placing the Circuit Playground TFT Gizmo on the Circuit Playground Express or Circuit Playground Bluefruit is pretty straightforward. All you need is a #2 Phillips screwdriver.
Info:
The amber colored Kapton tape dots must be removed from each of the twelve standoffs before assembling the boards. These are electrically insulating and will prevent the Gizmo from working properly if left in place.
You can use your fingernails or some tweezers or a pin to poke and lift each dot as shown here.
Start by aligning the two boards side by side like in the photo with the black plastic speaker connector and battery connectors pointing in the same direction.
Place the Circuit Playground board on top of the Gizmo being sure that the connectors mentioned in the previous step are still aligned.
Install a few screws loosely, so that all of the holes are still aligned, before tightening them down.
Finish installing the remaining screws. After that, you're done!
# Turtle Graphics in CircuitPython on TFT Gizmo
## Turtle Graphics on Gizmo
https://youtu.be/Yy3T2r5h6-o
## Libraries
Now we'll install the libraries that we need to use Turtle graphics on the Circuit Playground Bluefruit with TFT Gizmo.
[Click this link](https://circuitpython.org/libraries) to go to the **circuitpython.org** Libraries page. Download the latest version of the Bundle library .zip file that matches the version of CircuitPython you're using on the board.
Uncompress the **.zip** file and then copy the following directory and three library **.mpy** files to the **lib** directory of the **CIRCUITPY** drive:
- **adafruit\_bus\_device**
- **adafruit\_logging.mpy**
- **adafruit\_st7789.mpy**
- **adafruit\_turtle.mpy**
## The Mu Editor
Adafruit recommends using the free program Mu to edit your CircuitPython programs and save them on your Circuit Playground Bluefruit. You can use any text editor, but Mu has some handy features.
[See this page on the Circuit Playground Bluefruit guide](https://learn.adafruit.com/adafruit-circuit-playground-bluefruit/installing-mu-editor) on the steps used to install Mu.
## Turtle Graphics Code
Let's start of with a simple bit of code. It will draw a square on the screen.
Copy the code below and then paste it into a new document in **Mu**. Save it to the **CIRCUITPY** drive as **code.py**.
https://github.com/adafruit/Adafruit_Learning_System_Guides/blob/main/TFT_Gizmo_Turtle_Graphics/turtle_square01/code.py
## Square
After the setup code imports libraries and configures some pins for the display, the main body of the code runs. Watch the screen on your TFT Gizmo as the board restarts and runs the code.
First, it sets the pen down with the `turtle.pendown()` command. (Later, you'll learn to lift the pen with `turtle.penup()` so you don't always draw a line then the turtle moves!)
The turtle starts out at the origin point -- `0,0` on the x- and y-axis respectively. It then moves forward `80` pixels, drawing a line as it goes using the `turtle.forward(80)` command. This draws the top of the square.
Next, the turtle turns right using the` turtle.right(90)` command.
This same pair of commands -- `forward()` and `right()` -- run three more times in order to complete the square.
Since there are some repetitive steps in there, we can tidy up the code by iterating through a loop four times like this:
https://github.com/adafruit/Adafruit_Learning_System_Guides/blob/main/TFT_Gizmo_Turtle_Graphics/turtle_square_loop/code.py
Try out that code -- it's much shorter, but you'll see the same square drawn on the screen!
## Asterisk
Now that we can loop through a command many times, let's add another two commands -- `turtle.back()`and `turtle.left()`
We can move forward and backward to create a line, shift the angle 18 degrees to the left, and do it all again. After twenty iterations of this we have a nice star pattern!
With a small change to the code (see the comment on line 18) we can turn this into an iris pattern!
https://github.com/adafruit/Adafruit_Learning_System_Guides/blob/main/TFT_Gizmo_Turtle_Graphics/turtle_asterix/code.py
## Circle
The built-in command `turtle.circle()` makes it very simple to draw a triangle. No, just kidding! It draws a **circle**!
Try out the example here, and then us some different numbers for the circle radius instead of the 118 here.
https://github.com/adafruit/Adafruit_Learning_System_Guides/blob/main/TFT_Gizmo_Turtle_Graphics/turtle_circle/code.py
## Circle Petals
Let's get a little fancy. We will now introduce a few more techniques, including the `turtle.pencolor()` command to change the color of the line that our turtle draws, as well as iterating through multiple loops with changing variables.
This will allow us to change the size of a series of five circles, and repeat the pattern four times.
https://github.com/adafruit/Adafruit_Learning_System_Guides/blob/main/TFT_Gizmo_Turtle_Graphics/turtle_circle_petals/code.py
## Star
Here's a super stylish, 1970's inspired star! Note how the length of each forward command is increased as the value of `i` goes up during each of the 26 iterations of the loop.
https://github.com/adafruit/Adafruit_Learning_System_Guides/blob/main/TFT_Gizmo_Turtle_Graphics/turtle_star_fancy/code.py
## Rainbow Benzene
Here's a classic, beautiful design. This hexagonal shape twists with each iteration, and every side of each perceived hexagon is a different color of the rainbow!
https://github.com/adafruit/Adafruit_Learning_System_Guides/blob/main/TFT_Gizmo_Turtle_Graphics/turtle_benzene/code.py
## Parabolas
This lovely parabolic curve set creates the illusion of curvature. It is in fact made up entirely of straight line segments, just as you would with a piece of string art and some pins pushed into a canvas.
It also introduces the `turtle.dot()` command, which drops down a dot of your desired radius wherever the turtle is. In this case, the turtle is moved with `turtle.goto()` This command allows the turtle to instantly head to a coordinate point on the screen rather than needing explicit angle rotations specified along with a "forward" command.
https://github.com/adafruit/Adafruit_Learning_System_Guides/blob/main/TFT_Gizmo_Turtle_Graphics/turtle_parabolic_jack/code.py
## Sierpinski Triangle
Time to get fractal! These are recursive, equilateral triangles as described by Waclaw Sierpinski in 1915! [Read more about them here](https://en.wikipedia.org/wiki/Sierpi%C5%84ski_triangle).
https://github.com/adafruit/Adafruit_Learning_System_Guides/blob/main/TFT_Gizmo_Turtle_Graphics/turtle_sierpinski/code.py
## Hilbert Curve
Here's another interesting fractal pattern, called a [Hilbert curve](https://en.wikipedia.org/wiki/Hilbert_curve).
https://github.com/adafruit/Adafruit_Learning_System_Guides/blob/main/TFT_Gizmo_Turtle_Graphics/turtle_hilbert/code.py
## Koch Snowflake
This is a third generation fractal Koch snowflake.
https://github.com/adafruit/Adafruit_Learning_System_Guides/blob/main/TFT_Gizmo_Turtle_Graphics/turtle_koch/code.py
## Christmas Tree
This lovely Christmas tree was adapted from [this program written by Keith Randall.](https://codegolf.stackexchange.com/questions/15860/make-a-scalable-christmas-tree)
https://github.com/adafruit/Adafruit_Learning_System_Guides/blob/main/TFT_Gizmo_Turtle_Graphics/turtle_christmas_tree/code.py
## Snowflakes
This example will draw lots of beautiful snowflake-style patterns! If you want to get technical about the number of sides in your flakes, make some adjustments to this line:
`draw_flake(randint(5, 8)) #adjust number of arms here
`
https://github.com/adafruit/Adafruit_Learning_System_Guides/blob/main/TFT_Gizmo_Turtle_Graphics/turtle_snowflakes/code.py
## Where to Find More
You can find much more information about turtle graphics as well as example scripts through an Internet search of "turtle python graphics examples" or some variation. Since turtle graphics are mainly in terms of moving and turning they can usually be converted to CircuitPython and the **adafruit\_turtle** library.
Check out these example sites:
- [Michael0x2a Examples](https://michael0x2a.com/blog/turtle-examples)
- [Geeks for Geeks Examples](https://www.geeksforgeeks.org/turtle-programming-python/)
- [Vivax Solutions Examples](https://www.vivaxsolutions.com/web/python-turtle.aspx)
## Guide 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...
In 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)
### Fully Reversible Pink/Purple USB A to micro B Cable - 1m long
[Fully Reversible Pink/Purple USB A to micro B Cable - 1m long](https://www.adafruit.com/product/4111)
This cable is not only super-fashionable, with a woven pink and purple Blinka-like pattern, it's also fully reversible! That's right, you will save _seconds_ a day by not having to flip the cable around.
First let's talk about the cover and over-molding. We got these...
In Stock
[Buy Now](https://www.adafruit.com/product/4111)
[Related Guides to the Product](https://learn.adafruit.com/products/4111/guides)
### Lithium Ion Polymer Battery with Short Cable - 3.7V 350mAh
[Lithium Ion Polymer Battery with Short Cable - 3.7V 350mAh](https://www.adafruit.com/product/4237)
Lithium-ion polymer (also known as 'lipo' or 'lipoly') batteries are thin, light, and powerful. The output ranges from 4.2V when completely charged to 3.7V. This battery has a capacity of 350mAh for a total of about 1.3 Wh. If you need a larger (or smaller!) battery,
In Stock
[Buy Now](https://www.adafruit.com/product/4237)
[Related Guides to the Product](https://learn.adafruit.com/products/4237/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)
- [USB Morse Code Key with CircuitPython](https://learn.adafruit.com/usb-morse-code-paddle-with-circuitpython.md)
- [Bluefruit Playground Hide and Seek](https://learn.adafruit.com/hide-n-seek-bluefruit-ornament.md)
- [CircuitPython Day 2020 Countdown Clock](https://learn.adafruit.com/circuitpython-day-2020-countdown-clock.md)
- [RP2040 RunCPM Emulator with USB Keyboard & HDMI screen](https://learn.adafruit.com/rp2040-runcpm-emulator-with-usb-keyboard-hdmi-screen.md)
- [Pico W YBox3](https://learn.adafruit.com/pico-w-ybox3.md)
- [PyPortal 2FA TOTP Authentication Friend](https://learn.adafruit.com/pyportal-2fa-totp-authentication-friend.md)
- [3D Printed Case for Raspberry Pi Pico](https://learn.adafruit.com/raspberry-pi-pico-case.md)
- [Unicorn Christmas Stocking with Rainbow Lights & Sound](https://learn.adafruit.com/unicorn-christmas-stocking-with-lights-sound.md)
- [Custom Color Palettes for MakeCode Arcade Games](https://learn.adafruit.com/custom-color-palettes-for-makecode-arcade-games.md)
- [DIY Quiz Show Controller System](https://learn.adafruit.com/quiz-show-controller-keyboard-bluetooth.md)
- [Which CircuitPython Board is Right for You?](https://learn.adafruit.com/choose-your-circuitpython-board.md)
- [Tree with Animated Eyes and Motion Sensor](https://learn.adafruit.com/tree-ent-sculpture-with-animated-eyes.md)
- [PyBadge GamePad](https://learn.adafruit.com/pybadge-gamepad.md)
- [Bluefruit Luminary Lanterns with Capacitive Touch](https://learn.adafruit.com/bluefruit-luminary-lanterns-with-capacitive-touch.md)
- [Smart Mirror with PyPortal](https://learn.adafruit.com/smart-mirror-with-pyportal.md)