Welcome to the Circuit Playground Express Workshop! This workshop is geared toward educators and coding beginners, who want to get started programming with this easy to use platform. We will go over everything you need to know to get you started programming your Circuit Playground Express. We will focus on the educator friendly MakeCode programming interface. A little bit about me, my name is Stephen and I'm a life-long maker with a passion for microcontrollers and wearable devices.
To follow along with this workshop you will need a few things:
- An Adafruit Circuit Playground Express
- A Micro USB cord (be sure it's not just a power cord!)
- A computer or tablet with a USB port
Some optional components that will appear in the workshop but are not necessary to follow along:
- A Battery Pack
- Alligator clips
- Servo
- External LEDs (just about any NeoPixel is compatible)
If you run into any issues throughout the workshop, then please reach out on the forum. We are full time makes and here to help!
Course Outline
- Chapter 1: Introducing the Circuit Playground Express
- What is the circuit playground express
- A platform for Educators and beginners
- Choosing a programming language
- Chapter 2: Getting started
- Get to know MakeCode
- Powering and connecting your CPX
- Flashing your program to the board
- Chapter 3: Programming Fundamentals
- How does a program work?
- Inputs and outputs
- What is a variable
- Programming logic
- Overview of MakeCode programming blocks
- Advanced MakeCode programming blocks
- Chapter 4: Introductory Programs
- Controlling the LEDs
- Utilizing the Sensors
- Music
- Using External Devices
- Console Output
- Chapter 5: Communication
- Infrared Communication
- Turning your CPX into an HID Keyboard or Mouse
- Chapter 6: Other Ways to program
- Programming with Javascript
- Programming with CircuitPython
- Programming with Arduino
- Chapter 7: Crafting with the CPX
- Capacitive touch
- Securing your Circuit Playground
- 3D Printing a housing for the Circuit Playground
- Chapter 8: Where to go from here
- Where to find Inspiration
- Where to find help
Chapter 1: Introducing the Circuit Playground Express
1.0 Chapter Overview
What is the Circuit Playground Express and how easy is it to use? In this chapter, we will learn about the CPX and find out why its such a great option for educators and beginners. We will cover the following:
- What is the circuit playground express
- A platform for Educators and beginners
- Choosing a programming language
1.1 What is the Circuit Playground Express?
What is the Circuit Playground Express and what makes it so good for educators? The CPX is a feature packed board with so many sensors you can make countless programs without ever needing to solder or connect an external device. I'll explain all the features in the video, but here is a list of all the hardware features:
- 10 x mini NeoPixels, each one can display any color
- 1 x Motion sensor (LIS3DH triple-axis accelerometer with tap detection, free-fall detection)
- 1 x Temperature sensor (thermistor)
- 1 x Light sensor (phototransistor). Can also act as a color sensor and pulse sensor.
- 1 x Sound sensor (MEMS microphone)
- 1 x Mini speaker with class D amplifier (7.5mm magnetic speaker/buzzer)
- 2 x Push buttons, labelled A and B
- 1 x Slide switch
- Infrared receiver and transmitter - can receive and transmit any remote control codes, as well as send messages between Circuit Playground Expresses. Can also act as a proximity sensor.
- 8 x alligator-clip friendly input/output pins
- Includes I2C, UART, 8 pins that can do analog inputs, multiple PWM output
- 7 pads can act as capacitive touch inputs and the 1 remaining is a true analog output
- Green "ON" LED so you know its powered
- Red "#13" LED for basic blinking
- Reset button
- ATSAMD21 ARM Cortex M0 Processor, running at 3.3V and 48MHz
- 2 MB of SPI Flash storage, used primarily with CircuitPython to store code and libraries.
- MicroUSB port for programming and debugging
- USB port can act like a serial port, keyboard, mouse, joystick or MIDI!
1.2 A Platform for Educators and Beginners
The Circuit Playground Express is built with the new programmer and educator in mind the board is robust and contained and can be programmed from any device with an internet connection. Their contained package and easy to use programming options make for highly rewarding results without complex programming or troubleshooting.
1.3 Choosing a Programming Language
There are actually four different programming languages that you can use to program the Circuit Playground Express! This is some unprecedented versatility in the world of microcontrollers! In order from easiest to most complex they are:
MakeCode - a block-based visual interface with a virtual CPX on the screen to try your programs before ever needing to connect your hardware.
CircuitPython – based on the super popular Python programming language. Python is the most taught programming language in the world! CircuitPython is Python that’s made for a microcontroller
JavaScript - this is the language that's running behind the scenes in MakeCode. It's not the most popular programming language amongst makers, but it has been used in software for a long time and there is plenty of documentation available for learning.
Arduino - Based on C programming language, Arduino is the language that kicked off the maker revolution. A relatively complex language, this is offset by the wealth of open source programs and support available online.
Chapter 2: Getting Started
2.0 Overview
Now that you know what the circuit playground express is, let's learn about setting it up. Setting up is easy, but there are some important steps to follow. We will learn about:
- Get to know MakeCode
- Powering and connecting your CPX
- Flashing your program to the board
2.1 Get to know MakeCode
MakeCode is an exciting visual interface programmer that allows you to program by dragging and dropping blocks. The blocks snap together like puzzle pieces and are shaped in a logical way that prevents you from creating unworkable programs. This coupled with the on-screen virtual Circuit Playground Express makes MakeCode a perfect tool to learn the basics of programming. With a few clicks, you can get the same result of an hour of coding in another language. This makes for a very rewarding experience. Don’t be fooled though, just because it’s easy doesn’t mean that it’s not capable. MakeCode can produce quite complex programs, as well!
There are two different ways to use MakeCode, web browser based and the Windows App.
Web Browser - You can program using MakeCode from your web browser! No special software required, just an internet connection. Once you have loaded the website it no longer needs an internet connection to run. You can find the MakeCode editor at www.makecode.com
Windows App - MakeCode is also available as an installed application. There are a few advantages to using this version of MakeCode.
- You can read live data sent from your Circuit Playground Express within MakeCode.
- When you are ready to download your code, MakeCode will detect your connected Circuit Playground and load it on your board automatically.
- No internet connection required once the program is downloaded.
To get the Windows App version of MakeCode. Search the Windows Store for "MakeCode for Adafruit" and click "Get the App".
2.2 Powering and Connecting your Circuit Playground
The Circuit Playground Express runs on 3.3v. It can be powered by USB, or by a battery connected to the JST-PH connector. A USB supplies about 5v of power, but there is a built-in power regulator. The Circuit Playground can be powered by either a few AA or AAA batteries in a pack or by a LiPo battery. We recommend using an AA or AAA battery pack for ease of use and safety.
2.3 Flashing your Program to the Board
Setting up your Circuit Playground Express is easy, there are no extra steps to get your board ready to program, just make your code and drop it into the device drive by following these steps.
- Enter Bootloader Mode: Press the reset button once while the Circuit Playground is connected to the PC to enter bootloader mode. You should see the light ring turn red, then green when its ready. The Circuit Playground will appear as a drive on your computer called CPLAYBOOT. NOTE: You may need to press the reset button twice to enter bootloader mode.
- Transfer Your Code: Save your program in MakeCode, or hit Download to create a .uf2 file. This is the file type that the Circuit Playground reads programs on. Drag and drop your .uf2 file from wherever you saved it (probably the downloads folder) into the Circuit Playground drive CPLAYBOOT.
You're done! The Circuit Playground will reboot and begin running your code.
If you are using the Windows app version of MakeCode for Circuit Playground Express, it's even easier! You only need to manually drag the code (.uf2 file) onto the board the first time out of the box. From now on if the Circuit Playground Express is connected to the PC, you only need to hit the Download button in MakeCode. The app version of MakeCode recognizes your Circuit Playground and loads the code automatically. Your board will reboot and start running the code immediately! This is one of the big advantages of using the Windows App rather than the browser.
Chapter 3: Programming Fundamentals
3.0 Overview
Are you new to coding or maybe a bit rusty? MakeCode is a great resource for getting familiar with coding while enabling you to make rewarding programs from the start. In this chapter we will learn:
- How does a program work?
- Inputs and outputs
- What is a variable
- Programming logic
- Overview of MakeCode programming blocks
- Advanced MakeCode programming blocks
3.1 How Does a Program Work
In this section, we will learn the basics of a program's structure. In different programming languages, the names (syntax) will be different, but the general format will be similar. There are two main parts to every program, setup and loop. In many languages, there is a section where you set up the environment that your program will run within, and a section that will run on repeat continuously until the microcontroller is turned off or commanded to stop. In MakeCode the setup portion of the code would be inside an “on start” block, and the loop would be in the “forever loop”. This can get a little confusing in MakeCode because there are many blocks that do not need to be placed in a loop, but they are functionally the same as a loop. You can have multiple loop brackets in a single program in MakeCode, but it is functionally the same as if it was all within one loop.
3.2 Inputs and Outputs
The thing that sets programming a microcontroller apart from a computer program is its ability to interact with the world physically. If we want to have our controller accept a button press, that’s an input. If we want to turn a light on, that’s an output.
Inputs
There are many different available inputs on the Circuit Playground Express. The blocks that we use to interact with them are the pink INPUT category. There are two different classes of INPUT, Events and Live Data. Input Events are like a loop, and the blocks have the same shape as a loop. They wait for the condition to be met, run the code inside the block once, then continue waiting for the condition to be met again. Live Data returns the actual reading from a given sensor. This number changes constantly and can be used to graph the sound level or read the acceleration of the board. We recommend using live data and logic whenever possible because it is more configurable and its how you would use inputs in other programming languages.
Example
Shown here is the input category of blocks. The Event type are brackets, the Live data is oval.
Outputs
Outputs are how the microcontroller interacts with the world when commanded. This can be making a sound, turning on a light, or transmitting a signal. We will use lights and music most often in this workshop. Outputs must always be within a loop or an input event bracket.
Example
In this example, we have a pink Input Event bracket, if button A is clicked then the lights turn on red, and after a ½ beat pause, the lights are turned off. This will happen every time the button is pressed until the board is turned off.
On the right, we have a Forever loop that contains code that is functionally the same. If button A is pressed the lights are turned on, there is a ½ beat pause, and then the lights are cleared. This can be repeated until the board is turned off. The first example is easier for simple programs, but the second example has the same structure as traditional code.
3.3 What is a Variable?
A variable in code is exactly like a variable in math. We can create variables to store a value that might change and refer to it elsewhere in our code. This can be used to keep our code simple and clean, or it might be used for calculations and comparisons.
Example
Here is an example of a variable being used in the code. Within the forever loop, we first save the sound level as “variable”, we then graph the value of “variable”. You would never need to use a variable in this way since you could just use sound level directly and get the same result, but we will get into the more practical use of variables in the next section.
3.4 Programming Logic
The simplest sort of program can make a light blink, but if we want anything more complex, we need to start using programming logic. Programming logic is used in every program, and MakeCode is a great introduction to how these work. Let’s break them into three categories:
Conditionals
If
If the condition is True, then run the program contained within. If the condition is False the program contained within is bypassed.
If/else
If the condition is True, then run the program contained within. If the condition is False run the program contained within the “else” brackets.
Example
In the Example Below we have an If/Else statement. If Button A is pressed then it will play the power-up sound. If the button is not pressed then it will stop all sounds.
Comparison
This form of logic compares two values and returns a True or False depending on the result. A comparison can be "Does 2 = 2", the answer would be True. It is typically used with a variable such as “x >= 3”, which would return False if x was less than three, and True if 3 or greater
Boolean
Boolean logic returns a True or False, and are usually used in conjunction with a comparison. The Boolean operators are TRUE, FALSE, AND, OR, NOT, NAND, and NOR. True and False are what is returned whenever a comparison is made.
AND – Returns True if both inputs are True
OR – Returns True if at least one input is True
Example
In this example, we have a series of If statements that require either Both button A and B to be pressed, or either Button A or B to be pressed.
NOT – Returns True if the input is False. Returns False if the input is True
NAND and NOR are not available blocks in MakeCode, but they can be made by combining a NOT and AND block, and NOT and OR block. They return the opposite of AND and OR. NAND returns False if both inputs are True. NOR returns False if at least one input is True
Advanced Conditionals
While
A while loop works similarly to an IF conditional. Except a while loop runs whatever is contained within continuously while the condition is met. An If runs its contents once then continues the main loop.
For
A for loop runs its contents for a set number of times, then moves on. It uses an “index” variable that’s value is increased every cycle until it reaches the limit set. This variable can be used within the loop. This is used for simplifying repetitive tasks in your code.
3.5 Overview of MakeCode Programming Blocks
In this section we will discuss the available blocks in MakeCode, and what they do. There are eight main categories of blocks that we will discuss.
- Light
- Input
- Music
- Network
- Loops
- Logic
- Variables
- Math
3.6 Advanced MakeCode Programming Blocks
In this section, we will discuss the advanced programming blocks available in MakeCode. These are seldom used or needed in most MakeCode projects but can unlock a lot of potential within your programs. We will discuss:
- Pins
- Functions
- Arrays
- Text
- Console
- Control
- Extensions
Chapter 4: Introductory Programs
4.0 Overview
This chapter of the Circuit Playground Express Workshop will focus on making programs within MakeCode. We will learn about:
- Controlling the LEDs
- Utilizing the Sensors
- Music
- Using External Devices
- Console Output
4.1 Controlling the LEDs
The Circuit Playground Express comes with ten NeoPixel LEDs right on the board. Controlling them with MakeCode is easy! In this section will discuss the various ways to control the NeoPixels, and how to incorporate them into your project!
4.2 Utilizing the Sensors
There are eight different ways we can interact with the Circuit Playground straight out of the box, and no limit to the sensors and devices that we could connect externally. In this section, we will learn about how to interact with the various onboard sensors that come with the Circuit Playground Express. In this section we will discuss the following sensors:
- Thermometer
- Touchpads
- Microphone
- Light sensor
- Accelerometer
Looking for more projects that utilized the sensors? We created a full tutorial for each sensor on the Circuit Playground Express! Head over to our Circuit Playground Express Tutorials if you're interested.
4.3 Music
Time to play a tune on your Circuit Playground Express! In this section, we will discuss how to make music on your Circuit Playground! We will go over the basics of tune design and walk you through making a song of your own.
If you want to play around with my example sketch you can find it here: "For Elise" MakeCode sketch for The Circuit Playground Express
4.4 Using External Devices
Is your project growing beyond the scope of your onboard LEDs or sensors? In this section, we will discuss connecting external devices to your Circuit Playground Express. We will focus on connecting an external LED strip, and go over how to read and send data to other external devices.
4.5 Console Output
The Windows app version of MakeCode is made specifically for the Adafruit Circuit Playground Express and comes equipped with some extra features that the web browser version does not have. In this section we will show you one of the features added to the Windows App, console read. Using Console Read we view data sent from the Circuit Playground to the computer in real time. We can use this for troubleshooting or for taking readings.
Chapter 5: Communication
5.0 Overview
In this chapter, we will learn about how to make your Circuit Playground Express talk! This could mean communicating with another Circuit Playground or a computer. We will learn the basics of:
- Infrared communication
- Turning your Circuit Playground into a Mouse or Keyboard
5.1: Infrared Communication (IR)
In the centre of the Circuit Playground, to the left and right of the accelerometer is the infrared (IR) transmitter and receiver. Using IR to communicate on the Circuit Playground is easy! We use the network block to select a number to transmit, and a network block to receive numbers and store them as a variable. We can also send variables that are stored as numbers, such as RGB colours. Most of what happens when we send an IR signal happens behind the scenes.
When we transmit with infrared, we send pulses of light 28,000 times a second, with pauses in between each pulse. The receiver detects each pulse and measures the duration of time passed until the next pulse. The number of durations and the length of each duration creates a unique code that we can use in our software. Luckily MakeCode does all this for us. All we need to do is select a single number in the “infrared send number” block, and MakeCode creates a 52 duration pulse to transmit it. The receiving Circuit Playground converts it back to the same number as we sent.
In this example, we would load this same code on two Circuit Playgrounds. When button A is pressed it will send an IR signal “1”. When an IR signal is received it will check to see if it’s a “1” and turn the LEDs red if true. I also included an example of how you can transmit LED colours in the place of numbers.
5.2 Turning Your Circuit Playground into a Mouse or Keyboard (HID)
The Circuit Playground Express can be recognized as an HID device by a computer, and we can use MakeCode to program it! Under the Advanced menu, there is an option for “Extensions” there we can add the ability to use the Circuit Playground as a Mouse, Keyboard, or even a gamepad! New blocks will appear to be able to perform these functions once they are selected under extensions.
I found that I was unable to use live sensor data to control the mouse position. This caused the board to crash every time. So using the accelerometer on the board to control the mouse is off the table for now. You can use buttons, capacitive touch, and external inputs to control the mouse position though.
You can also turn your Circuit Playground into a keyboard! In this example, I created a capacitive touch keyboard to type my most used phrase out for me with the press of a button! Talk about efficiency!
Chapter 6: Other Ways to Program
6.0 Overview
Is your project getting too complex for MakeCode? Interested in exploring the other ways that we can program the Circuit Playground Express? Luck for you there are three more ways that we can program the Circuit Playground! By now we are familiar with MakeCode, so let’s take a look at the other ways.
- Javascript
- CircuitPython
- Arduino
6.1 Programming with Javascript
To program with Javascript you use the MakeCode editor but change your interface to be Javascript. Javascript is easy to program, and all the commands that are available in MakeCode are also available in Javascript. One of the coolest features of programming in Javascript within MakeCode is that you retain all the great libraries that MakeCode offers. Plus, you can drag and drop code segments from the menu column just like blocks. This seriously speeds up programming!
There is a lot of info available for people looking to learn Javascript. If you are completely new to Javascript there are hundreds of free online lessons, and fun apps to help you learn like Grasshopper! Javascript is a very widely used language, and even though it isn't very common amongst maker products, there is still a huge number of people using it, so finding direction when you hit a snag should be easy.
6.2 Programming with CircuitPython
CircuitPython is based on the Python programming language and is a derivative of MicroPython created by Adafruit. What does that mean to the user? CircuitPython is like Python with added support for hardware, and its designed for the education platforms that Adafruit makes.
CircuitPython is easy to program and has a simple interface that reduces the opportunities for errors when creating code. There are many libraries created for use with the Circuit Playground Express that make programming even easier. Python is one of the most popular new programming languages today, and it is the most taught language in schools and universities!
CircuitPython doesn’t require a compiler, you can create your code with a text editor and send it straight to your Circuit Playground! Its easier to program with a Python editor though. We recommend Mu. The Mu editor is free and has native Circuit Playground support.
One of the big advantages of the CircuitPython is its REPL serial monitor. You can create programs live off the Circuit Playground with this feature. It's great for troubleshooting your code!
To learn how to get started with CircuitPython, check out our Introduction to CircuitPython Tutorial!
6.3 Programming with Arduino
Arduino is the most common programming language amongst maker electronics, and it has the lowest level control of any of the programming languages available to the Circuit Playground. This means that you have the greatest control when using this language. The other side of the coin is that Arduino can be a difficult language to learn, with somewhat complex syntax. The good news is that there is a huge community of people using and sharing Arduino programs. You can always find code online that is similar to your project or find and adapt the available code. If you ever got stumped with your code, you could definitely find someone with the skills willing to help out.
To learn more about the different ways to program the Circuit Playground to take a look at our Circuit Playground Overview Tutorial.
Chapter 7: Crafting with the Circuit Playground
7.0 Overview
You’ve got your project working, now its time to mount it. It could be on the end of a wand or in a 3D printed box. In this section, we will learn a little about creating a safe housing for the Circuit Playground. In this section we will cover:
- Capacitive touch
- Securing your CPX
- 3D Printing a housing for the CPX
7.1 Capacitive Touch
One of the fun features of the Circuit Playground is the capacitive touch-sensitive pads. They can be a little finicky sometimes, so this section is about making the most of the capacitive touch-sensitive pads. By there very nature capacitive touch sensitive pads are sensitive. They are detecting the slightest change in capacitance, so touching or moving a connected wire, having a wire too close to another and attaching a wire after the Circuit Playground is powered will all give false readings. To have the best capacitive touch experience:
Ensure all connections are solid
Do not move connected wires after the board is powered
Reset the board if you change something connected
7.2 Securing your Circuit Playground
When making a project with the Circuit Playground, perhaps the most important step is securing the board to the project. This applies whether what you are making is a jacket, box or magic wand. It is safe to use bolts, threads, alligator clips and just about anything else to secure your Circuit Playground. There are a lot of 3.3v and GND pins available, so I recommend using these as your anchor points.
Keep in mind that if you use conductive material like a bolt to secure your Circuit Playground, you must attach it to a non-conductive material. If you bolt your Circuit Playground to metal in the shown pattern you will short your board!
If you are looking to secure you Circuit Playground to a solid object, these are the hole dimensions you will need:
7.3 3D Printing a Housing
One of the best ways to create a housing for the Circuit Playground is to 3D Print one! There are a couple of things you should keep in mind when creating a 3D printed box for your project!
Use Standoffs
Standoffs to attach the board keep your project looking clean and professional. Then you can bolt your board to the box. Make sure the standoffs are tall enough to accommodate the bolt length. When making a standoff on a 3D printer make the hole for the bolt 0.5 mm larger than the bolt. This should allow the threads to just grab once printed.
Make a hole for a USB cord
If you decide to change your project you don’t really want to have to unbolt your board from the project box, so unless your confident that the box will be your final iteration of the project you are creating it's always nice to be able to get a USB cord in there to make changes easily.
Make room for a battery
Making your project mobile is half the fun of a good box. Be sure to make space for whatever battery you plan to use. When drawing up your design its good practice to make an object the size of your battery so you can make sure it fits before you print!
Chapter 8: Where to Go from Here
Where to find inspiration:
If you're looking for more ideas for things to do with the Circuit Playground Express, you can start by checking out our Circuit Playground Tutorials! Our tutorials are geared toward teaching how to use all the available options on the Circuit Playground If you want more fun projects, check out Adafruits Circuit Playground Tutorials. At the time of writing this, they have over 120 projects using the Circuit Playground Express, and they add more all the time!
Where to go for help:
The best place to find answers is our best friend Google. Chances are if you have a problem, your not the first person to have it. You can also find help over at the Adafruit website, and if that doesn’t help we are always available to help on our forums.