CircuitMess CircuitPet DIY Handheld Virtual Pet Installation Guide

CircuitMess CircuitPet DIY Handheld Virtual Pet

Product Information: CircuitPet Coding Tutorial

The CircuitPet coding tutorial is a guide for coding the newly-assembled handheld virtual pet using CircuitBlocks, a custom-made coding app designed by CircuitMess. The tutorial provides step-by-step instructions for installing CircuitBlocks and coding the CircuitPet in a graphical block-based coding interface. The tutorial is suitable for beginners who want to learn about physical computing.

Installation

CircuitBlocks currently runs on Windows, Linux, and Mac OS computers. The following instructions are provided for each operating system:

• Windows: Go to the CircuitBlocks download page and download the latest version for Windows. Check if you have a 32 or 64 version. Double-click the downloaded file named CircuitBlocks, and the app will automatically install and create a new desktop shortcut.
• Mac: Go to the CircuitBlocks download page and download the latest version for Mac OS. Move the files to the `Applications’ folder, and CircuitBlocks will be installed automatically.
• Linux: Go to the CircuitBlocks download page and press the Linux 64-bit download button. Double-click the file to run the installation (Ubuntu) or open the terminal and write sudo dpkg -i (Other Linux distros). CircuitBlocks willautomatically install and create a desktop entry. For stand-alone installation, press the Linux AppImage download button, right-click on the file, select Properties’, go to ‘Permissions’ and tickAllow executing file as program’, double-click the file, and the installation will complete automatically.

If you encounter any issues with the installation, please reach out to us via email at [email protected] and provide a screenshot of your issue and any information you find relevant.

Product Usage Instructions

To create a new CircuitPet project, follow these steps:

1. Open CircuitBlocks app on your computer.
2. Press the big New project button.
3. Choose CircuitPet as the device and Block as the Sketch type.
4. Press the Create button.

You will now see a screen with a toolbar on the top. The toolbar has a few buttons for various functions. You can start coding your CircuitPet using the graphical block-based coding interface provided by CircuitBlocks.

CircuitPet coding – first steps
Introduction
Installation
Welcome to the CircuitPet coding tutorial
Thank you for supporting CircuitMess, and welcome to the CircuitPet coding tutorial. We’ll use CircuitBlocks for coding your newly-assembled handheld virtual pet. CircuitBlocks is a custom-made coding app that we’ve designed. You will code your CircuitPet in CircuitBlocks’ graphical block-based coding interface that will help you make your first steps in the world of physical computing.
Installation
1 / 85

CircuitBlocks currently runs on Windows, Linux, and Mac OS computers.

If you have a Windows computer

1. Go to the CircuitBlocks download page 2. Download the latest version for Windows – Check if you have a 32 or 64
version. Go to Settings on your PC, click on the System option and find the About section where you’ll see the system type. 3. Double-click the downloaded file named “CircuitBlocks” 4. CircuitBlocks will automatically install and create a new desktop shortcut
Your PC is not at risk! There is a possibility that a notification that says your PC is at risk may pop up when you try to install CircuitBlocks. Don’t worry; this happens regardless of CircuitBlocks being safe to run. See the instructions below on how to handle this notification.
2 / 85

This is the message you might get when installing CircuitBlock on your PC. Windows reports a threat despite the program being safe to download and run. Please proceed with the installation by clicking on the ‘More info’ option.
3 / 85

After you click on the ‘More info’ option, the ‘Run anyway’ option should appear at the bottom of the window. Proceed by clicking on ‘Run anyway’.

If you have a Mac computer

1. Go to the CircuitBlocks download page 2. Download the latest version of CircuitBlocks for Mac OS (the file named
“CircuitBlocks-1.0.1-Mac.dmg” or similarly should be downloaded) 3. Move the files to the `Applications’ folder 4. CircuitBlocks will be installed automatically
If you have a Linux computer
1. Go to the CircuitBlocks download page 2. Press the “Linux 64-bit” download button 3. Double-click the file to run the installation (Ubuntu)
or
4 / 85

Open the terminal and write sudo dpkg -i <path to the downloaded file .deb> (Other Linux distros) 4. CircuitBlocks will automatically install and create a desktop entry Stand-alone (AppImage): 1. Go to the CircuitBlocks download page 2. Press the “Linux AppImage” download button 3. Right-click on the file and select Properties 4. Go to ‘Permissions’ and tickAllow executing file as program’ 5. Double-click the file, and the installation will complete automatically
If you encounter any issues with the installation, please reach out to us via email at [email protected] and provide a screenshot of your issue and any information you find relevant.

The basics

User interface
5 / 85

When you open CircuitBlocks, you will see a window that looks like this. It’s pretty simple ­ starting a new project (we also call them “sketches”) can be done by clicking the `New project’ button. Saved sketches will appear right next to that button and you can access them at any time. If you encounter any kind of an issue with CircuitBlocks, press the ‘Send error report’ at the bottom of the main screen. You’ll get an error report number – please reach out to us via [email protected] and provide your error report number.
Creating a new project (sketch)
Press on the big “New project” button. You’ll get an option to choose the device and sketch type. For the device, pick CircuitPet. For the Sketch type, choose Block. Press the Create button.
6 / 85

You’ll get a screen that looks like this:
On the top of the screen, there is a toolbar with a few buttons.
7 / 85

The block selection bar is located on the far left – you can take the blocks from there and drop them into the “drawing” area in the middle of the screen. In the middle of the screen is where you’ll be “drawing” your code with colorful blocks. On the right side of the screen, you will see code written in C++ appear magically by itself when you drag and drop the colorful blocks. C++ is one of the most popular programming languages, but it’s fairly complex to understand if you’ve never coded before. That’s why we’ve created CircuitBlocks – here, you can drag and drop colorful blocks that represent parts of code and see what your program would look like in C++. When you get skilled enough, you will be able to switch directly to textual coding in C++ without the need for colorful blocks.
Toolbar
Here’s a short explanation of what the buttons in the window toolbar do: 1. Back to the main menu ­ returns you to the home screen without saving 2. Save/Save As ­ saves your sketch, make sure to press this button from time to time, and before closing CircuitBlocks 3. CircuitPet connection indicator – the red dot turns green if your CircuitPet is connected to your computer via a USB cable 4. Sprite editor – for drawing characters you want to have on your CircuitPet.
8 / 85

5. Export to binary – saves a binary file of your code to your computer. This is a more advanced function that you won’t need for now
6. Serial monitor – this button opens a window that we call the “Serial monitor”. “Serial” is a nickname for a type of communication that is happening between CircuitPet and your computer. In this window, you will later be able to see the messages sent from CircuitPet to your computer via the USB port.
7. Close code – with this button, you can close or re-open the code window on the right of the screen. This is useful if you need more screen space for seeing your colored blocks.
8. Run – This button will translate the code you have constructed in CircuitBlocks to machine code that CircuitPet understands (beep boop beep boop 1011100101) and send the code to your CircuitPet via the USB port.

Code window

9 / 85

The so-called “Code window” has the following parts: 1. Main code screen – code written in C++ will appear here as you drag and drop colorful blocks on the left side of the screen. You’ll see that some parts of the code are colored in funny colors. Programmers call this syntax highlighting. Basically, what is happening is that different categories of code commands are colored differently so that programmers can understand the code more easily. 2. Light/dark theme switch – you can toggle the background and text color of the code window with this button. 3. Expand – stretches the code window across the entire screen. Press it again to resize it to the half-screen again. 4. Close ­ closes the code window, the same functionality as the toolbar’s `Close Code’ button.
Drawing board
The drawing board is where the magic happens.
10 / 85

It has the following parts:
1. Search bar ­ type the component’s name you are looking for here. 2. Component selector ­ the blocks are divided into different categories here.
Each category has a specific color designated to it. 3. Drawing area ­ you will drag the blocks from the component selector and
drop them into the drawing area. This is how code is made. Easy peasy! 4. Center tool – if you get lost when scrolling across the drawing area, press this
button, and it will center your view on the blocks you have dropped on the drawing area. 5. Zoom buttons – to zoom in and out of the drawing area.

Types of blocks

11 / 85

There are a total of nine block types in CB. Each of them is represented by their color. Every block translates to code, which is then compiled and uploaded to the phone, just like on every Arduino based platform.
Pressing on every block type will open a section from which you can drag and drop those blocks into the drawing area.
Also, pressing on `More’ will open even more blocks that are not so commonly used.
There are two main functions of every Arduino code ­ void setup() and void loop().
Everything that goes into the void setup() the function will run only once. It is primarily used to start the software, initialize and declare variables, and run functions that only have to run once (ex., Intro screen in a video game).
The void loop() is where everything else takes place. It basically runs every bit of code inside it repeatedly (speed depends on the device ­ just imagine it’s ultrafast!). It should pretty much follow the screen’s refresh rate and make the program do things accordingly.
Every block you place automatically goes into the void loop() function.
If you wish to put something in the void setup(), you have to drag the main block from Functions and place your blocks inside as you wish, but more on that a little bit later.
Elliptical blocks
Elliptical blocks represent variables. Whether we’re talking about integers, strings, or other variable types (other than Boolean), they can all be recognized by the same shape.
Also, larger blocks with elliptical shapes return either integer or float values.

Whenever you find circular “holes” inside some blocks, you can insert variables. It’s most commonly found in comparison or action blocks.

12 / 85

Triangular blocks
Triangular blocks represent boolean variables. Both variables (true and false) and functions that return boolean values have the same shape.
Regardless of color, each of these blocks returns either true or false. Triangular “holes” require boolean blocks to be inserted.
Building blocks
Everything else is basically a building block. Those are functions that have no return value (they return null). Both elliptical and triangular blocks must first be placed inside the building blocks to act as part of the program. They have a specific “puzzle” shape and can be stacked inside each other.

The main building block is located inside the `Functions’ section. It basically gives you two main building blocks sections.

13 / 85

Everything placed inside Arduino runs first goes into void setup(), and everything placed inside Arduino loop forever goes into a void loop().
Inserting blocks
Now, this is the main part. The whole point of blocks-like IDE is connecting blocks and placing them inside another. It is all done by simple drag-and-drop action. Here is an example of a program that will set the variable Var to 1 and then increase that variable while it is smaller than 10. At the end of the program, Var will be 10. This is just a simple example, and block-building will be further explained in the following chapters.

Block sections

There are a total of nine sections in CircuitBlocks. We’ve organized them so that you’ll be able to find everything in a maximum of two clicks.

14 / 85

The sections themselves are pretty self-explanatory, but we’ll go through them all to get a little better understanding of the whole concept. Some of the sections also have additional blocks (in the ‘More’ menu) where you’ll be able to find some of the functions that are not used that often but can still be useful.
Logic
Every if, if-else, else function, comparisons, and/or, not, true/false, and other logical operators.
Loops
Loops are functions that repeat everything inside for a specific amount of time.
15 / 85

They can have conditional and repeat for as long as that condition is met or have a pre-determined number of repeats.
Math
Pretty much every math function is located here. From basic operations to rounding numbers and working with angles, you will easily trigger your inner Einstein or Pythagoras in a matter of seconds!
16 / 85

17 / 85

Text
Strings, characters, and string manipulation. Great place for creating new text and implementing it in your programs.
18 / 85

Variables

Create a variable of any type and set its name and desired value. CB will automatically recognize the variable type (int, double, string, boolean), so you don’t need to worry about that.
19 / 85

Functions
The Default Arduino function (explained on the previous page) is located here. You can also create your functions which can then be inserted as one of the main parts of your program.
20 / 85

Input/Output
Everything regarding CircuitPet’s components is located here.
21 / 85

Time
Delays, timers, and other time-related stuff, are great for creating cool animations and video games.
22 / 85

Search bar
There is also a search bar above all function sections to ease the search for that one specific block you just can’t seem to find. Just type in whatever comes to your mind, and all blocks that have anything to do with the written word will be shown on the right-hand side. Now, you really can’t say that it’s impossible to find something. You’ve learned everything about the blocks! It’s time to move on to the next lesson…
Let’s start! Step by step
23 / 85

Blink, blink!

Let’s get down to business! Before doing anything, you need to connect your CircuitPet to your computer’s USB port and turn it on.
If everything is okay, CircuitBlocks should say “CircuitPet connected”.
If CircuitBlocks didn’t recognize your CircuitPet, please check if the USB cable is plugged in properly and if you are using a working USB port on your computer. If you still cannot get CircuitBlocks to recognize your CircuitPet, something possibly
24 / 85

went wrong with the driver installation on your computer. Drivers are these little programs that help your computer communicate with CircuitPet, and they sometimes act funny. Reach out to us via email at [email protected] if you cannot get your computer to recognize your CircuitPet.
Let’s play with the LED!
The first thing we’ll learn how to code is – how to make your LED blink in different colors! The first block that we need to find says “set RGB LED color”. This particular block controls whether LEDs are turned on or off. Because LED is one of CircuitPet’s output components, you can find the block you need in the I/O block section.
25 / 85

When you click “off,” you’ll be presented with a color palette from which you can choose. We went with red this time, but you can use any color you want.
The beginning of your code should look like this by now:
26 / 85

Because we want the LED to blink, we have to set the time that will pass between the LED turns on. For that, search for a time block that looks like this:
27 / 85

Once again, you can choose whatever time you want. However, we decided that the time between two LED blinks should be one second.
28 / 85

To make it more fun, we decided that each blink would be in a different color. To do so, either repeat the steps we took for the first two blocks or simply click the right mouse button and select the duplicate option.
29 / 85

As you can see, the second color that will shine is cyan. Now, we have to set the amount of time that will pass between the first and the second blink. To do that, simply duplicate the “wait 1 seconds” block.
30 / 85

Let’s do this once again! Duplicate both blocks (the color and the time one), and fill in the circles with yellow and 1. This is what your code should look like by now:
31 / 85

Now, hit the big red “Run” button and watch the code compile. If this is your first time doing it, the code may take up to a minute to compile. But don’t worry; the compilation should be faster after that. When you hit the Run button, the red line will appear beneath the Toolbar representing the percentage of code that’s compiled. Once the code is compiled, your CircuitPet will restart, and the LED will start blinking in red, cyan, and yellow at one- second intervals.

Display time!

Your first sketch was successfully coded.
Are you ready for more?
32 / 85

We’ll now see what we can do with the display. While working on the display, we will mostly use the display block section. In this task, we will try to write on CircuitPet’s display. A good thing to know is that if you have to write something on your display, firstly, you will have to set the font size, font type, and font color.
So, let’s start!
Let’s look for the font size block that looks like this:

You can make your letters whatever size you want.

33 / 85

Now, let’s set the font type. It’s in the same block section as the previous one.
34 / 85

This is what your code should look like by now:
35 / 85

The last thing we have to determine is the font color.
36 / 85

We chose navy for the font color, but you can use any color from the color palette.
37 / 85

Let’s make the main part of this sketch – write a sentence (or a word) you want to print on display. To do that, you’ll have to use this block:
38 / 85

As you can see, there are three white circles used for writing. The first one, next to print, determines the sentence that will appear on display. The “x” and “y” mark coordinates where the text will appear on display. We decided to write “Hello, world!” on the screen, but we kept the coordinates.
39 / 85

The last thing you need to do in this sketch is click on a “draw sprite to display” block. We need to use this block to ensure this code will appear on display.
40 / 85

41 / 85

Hit the big red Run button and wait for the code to compile!

Play with the inputs!

Now that you know a thing or two about CircuitBlocks, it’s time for a bit more advanced sketch. Go to the Display section, and click on the “set font size to” block.
42 / 85

Change the size to 1.

43 / 85

Now is the time to set up the font type.

44 / 85

45 / 85

Another thing that needs to be changed is the font color. We chose red, but you can use any color you want.
46 / 85

47 / 85

Here’s a block we haven’t used yet – a “clear the display” block. You can find it in the display block section as well.
48 / 85

This block will clear the display with some color so we can clearly see the sentence (or word) you’ll print.
49 / 85

Now we get to choose what we want to put on display. You can do it just like in the previous example. First, find this block:
50 / 85

Then write the text. Since we want to show you how to do cool things with CircuitPet’s buttons, we’ll put the text explaining what to do.
51 / 85

We separated the text into two blocks to fit on CircuitPet’s display. Now comes the main part – deciding which button will perform which function. When you press CircuitPet’s buttons, we trigger a particular event. Luckily, we have a specific block defined for that, and it’s under the I/O section. I/O stands for “Input/output”. CircuitPet’s buttons are the so-called input devices because they send an electrical impulse to the CircuitPet computer when triggered. CircuitPet’s display is an example of an output device because CircuitPet sends signals to it to display information. You need to find this purple block named “When button left gets pressed”. Place the block onto the drawing area.
52 / 85

Look for the “clear display” and “print” blocks in the display block section.
53 / 85

What we did here is we triggered CircuitPet so that when the left button gets pressed, the display will clear in black, and you’ll be able to see the word “left” on it. To carry out this command, we must insert the “draw sprite to display” block!
54 / 85

Now we have to create the same block, just for the right button. You can either repeat the steps or click duplicate and make a few changes. Make sure that one block says left, and the other says right button. It should look like this:
55 / 85

Duplicate the block once more, but this time change it to the enter button. Make sure that the print says “Enter press,” that variable “x” is set to 45, and variable “y” is set to 90.
56 / 85

Let’s make another copy of this block! Now we have to code what will happen when we release the enter key. Also, when you release the enter, make sure the print says “Enter release.”
57 / 85

Let’s duplicate the block one last time. We’ll code it for the back button this time. As always, we have to put the proper text and ensure the variables are set.
58 / 85

We’re almost done! Finally, drag and drop the “draw sprite to display” block under the “Arduino run first” section to ensure you can see everything on your CircuitPet. In the end, your code should look like this:
59 / 85

Hit the Run button and watch the code compile! Yaay! You learned how to code a slightly more difficult example. Don’t worry, there are more cool examples coming in the next chapter!
Buzz around!
Let’s learn what to do with the buzzer soldered to your CircuitPet. As the word itself says, the buzzer is used to make buzzing sounds. We’ll make a very similar sketch to the last one, but this time, pressing the buttons will trigger a particular sound to come out of the buzzer.
Let’s start!
For the beginning, go to the Display section and select the “set font size to” block.
60 / 85

As with the previous two sketches, we’ll change the font size to 1.
61 / 85

The next thing to do is choose a font type, another block in the Display section.
62 / 85

Click on the block and drag it into the drawing area.
63 / 85

And now, let’s set the font color.

64 / 85

This time we choose our font to be yellow.
65 / 85

Now that we’ve created a font let’s change what happens with the buzzer when a specific button is pressed or released. As in the previous sketch, we’ll use I/O blocks to determine what happens when specific buttons are pressed.
66 / 85

67 / 85

Let us introduce you to a new block called “Play tone with frequency 1000 Hz for 500 milliseconds”.
68 / 85

Click on the block, and drag it into the I/O block in the drawing area We changed the milliseconds to 200, but you can make it as long or as short as you like.
69 / 85

Let’s clear the display in purple once we press the right button.
70 / 85

You can choose what will be written on the display once the button is pressed.
71 / 85

72 / 85

For example, the screen can say “boop” when we press the right button. Don’t forget about the coordinates! Let’s make “x” 65 and “y” 60. And for the end, drag the “draw sprite to display” block for a sketch to work.
73 / 85

First button – DONE!

74 / 85

Since we’ll need the same blocks, we can easily duplicate them. Let’s do one button at a time.
75 / 85

The first one we’ll do is for when a left button gets pressed. We decided to play tone with a frequency of 2000 Hz this time, but we kept the same amount of time we’ll play that tone for. The screen’s color stays purple, but we’ll print “Beep” this time. Let’s duplicate the block again. Now, we’ll use a button for going back and playing tone with a frequency of 3000 Hz for 50 milliseconds. In the meantime, on the screen will be written “Ding”. Note that we kept coordinations the same for all prints.
76 / 85

Yes, you guessed it right! It’s time to duplicate some more blocks. The last button we’ll use is the enter one. In this sketch, we won’t do anything with releasing this button. If you press the enter button, the buzzer will play tone with a frequency of 100 Hz for 150 milliseconds. While the tone is playing, the screen will say “Buzz”.
77 / 85

Great! We used all of the four buttons from CircuitPet. We should do something with the screen once CircuitPet turns on. The best thing we can do is write what will happen next on the screen. To do so, we’ll need to jump to the Display section and use a couple of blocks. The first thing we want to do is clear the display so that the text can be transparent. To do so, use this block:
78 / 85

This block needs to be dragged to the Arduino run first block section.
79 / 85

Since we cleared the display, it’s time to write something on it.
80 / 85

Drag a circled block in the Arduino run first section. Also, you’ll need two of these blocks so the text is nicely placed in the middle of the screen.
81 / 85

So, the text that will be written on display once you turn your CircuitPet on will say, “Press one of the buttons!”. Basically, this is like an on-screen guide. And, we hope you know what must be placed at the end of every sketch. The “draw sprite to display” block!
82 / 85

You did it! Congrats! Hit the big red Run button, wait for a code to compile, and check it out. Once the code is compiled, your CircuitPet should restart, and the screen will turn yellow with the purple sign saying, “Press one of the buttons!”.

Restore CircuitPet’s firmware!

Once you’re done coding and just want your CircuitPet to be “normal” again, you need to restore his base firmware.
83 / 85

This is quite simple, just connect your CircuitPet to the USB port of your computer and press the “Restore firmware” button on the top right.
You will be prompted with a window to choose the device you are restoring the firmware for. Choose CircuitPet, of course.
Wait for a few seconds, and your CircuitPet will be back and running like usual. You need to do this whenever you’re done coding your CircuitPet if you want him to revert to his initial out-of-the-box functionality.

What’s next?

84 / 85

You’ve reached the end of first CircuitPet’s coding tutorial, congratulations!
We hope you’re as excited as we are about CircuitPet’s future since there are so many cool things we want to do with it in future firmware and CircuitBlocks updates. In the meantime, continue exploring on your own and show us what you’ve done with your CircuitPet by sharing it on the CircuitMess community forum or via our Discord channel. If you need any help with your device, as always, reach out to us via [email protected], and we’ll help as soon as we can. Thank you, and keep making!
85 / 85

References

• DIY STEM Kits for Kids | CircuitMess
• Download | CircuitBlocks | CircuitMess
• CircuitMess community
• Discord
• Download | CircuitBlocks | CircuitMess

Read User Manual Online (PDF format)

Download This Manual (PDF format)

Download this manual  >>