Overview

by Isaac Wellish
circuitpython_1.png

Are you familiar with block-based programming and trying to make the jump to Python?

You're in luck! EduBlocks is a web-based programming interface that is making the transition from block-based programming languages like Scratch to the syntax-based language Python easier.

If you've never programmed before and are new to block-based programming altogether, check out the block-based language MakeCode first. There's a helpful guide on that here.

In this guide we will go through the EduBlocks editor interface and different code blocks.

Next, we'll see how to upload code to the Circuit Playground Express and troubleshoot any issues. The Circuit Playground Express (CPX) is a great introduction to coding and electronics. Click here to learn more!

Last, we will go over different applications and examples of how to program the CPX to blink an LED, switch NeoPixel colors with buttons, and lastly make a touch-based drum machine!

EduBlocks is still in Beta. It might be rough around the edges!

Adafruit Parts:

Circuit Playground Express

PRODUCT ID: 3333
Circuit Playground Express is the next step towards a perfect introduction to electronics and programming. We've taken the original Circuit Playground Classic and...
$24.95
IN STOCK
Add to Cart
USB cable - USB A to Micro-B

USB cable - USB A to Micro-B

PRODUCT ID: 592
This here is your standard A to micro-B USB cable, for USB 1.1 or 2.0. Perfect for connecting a PC to your Metro, Feather, Raspberry Pi or other dev-board or...
$2.95
IN STOCK
Add to Cart

Optional parts:

Short Wire Alligator Clip Test Lead (set of 12)

Short Wire Alligator Clip Test Lead (set of 12)

PRODUCT ID: 1592
Connect this to that without soldering using these handy mini alligator clip test leads. Approximately 4.5" overall cables with alligator clip on each end, color coded. You get 12...
$3.95
IN STOCK
Add to Cart
Small Alligator Clip to Male Jumper Wire Bundle - 12 Pieces

Small Alligator Clip to Male Jumper Wire Bundle - 12 Pieces

PRODUCT ID: 3255
For bread-boarding with unusual non-header-friendly surfaces, these cables will be your best friends! No longer will you have long strands of alligator clips that are grabbing little...
$7.95
IN STOCK
Add to Cart

Sound amplification parts:

  • A speaker or amplifier with an 1/8" or 1/4" input

If using a speaker with 1/8" input:

3.5mm (1/8") Stereo Audio Plug Terminal Block

3.5mm (1/8") Stereo Audio Plug Terminal Block

PRODUCT ID: 2790
One truth about working with audio is you always need the cable or adapter you don't have in your toolbox. That's why we love these terminal-block audio connectors so...
$2.50
IN STOCK
Add to Cart

If using an amp with 1/4" input:

1/4" (6.35mm) Stereo Plug Terminal Block

1/4" (6.35mm) Stereo Plug Terminal Block

PRODUCT ID: 2911
One truth about working with audio is you always need the cable or adapter you don't have in your toolbox. That's why we love these terminal-block audio...
$1.95
IN STOCK
Add to Cart

To trigger drum sounds:

  • Spare coins or other capacitive touch materials like aluminum foil or even fruit!

Navigating EduBlocks

by Isaac Wellish

The quickest way to get started with EduBlocks is to jump right in! The programming language is web-based, which means there is no downloading necessary. Just head to the website below.

After entering the site, you will be taken to the EduBlocks project editor. This is where all the coding happens!

circuitpython_2.png

User Interface

by Isaac Wellish

The EduBlocks user interface is the area on your screen where the CircuitPython program exists. The screen is divided into multiple sections, which have different functions, from picking blocks to code with, to downloading a CircuitPython file. We will go through the different elements of the interface

  • On the right side of the screen is our editing space. This is where we'll drag and drop blocks onto to create our program.

  • The left column is where we'll find all the different blocks with which to choose from.

  • The toolbar on the top allows us to create new programs, open old ones, save current ones, add extensions, load sample programs, change themes and lastly switch between CircuitPython syntax code and blocks.

  • The CircuitPlayground logo at the top will allow you to change modes. EduBlocks supports other platforms like the micro:bit, Raspberry Pi and also Core Python. We won't need to use it in this tutorial, however, you can explore the different platforms if you like.

Block Types

by Isaac Wellish

EduBlocks is a "block-based" programming language. This means instead of writing lines of code to program, we use "blocks". Each block has a specific category that describes what its purpose is. In EduBlocks, each block type corresponds to a library in CircuitPython.

Each CircuitPython program you run needs to have a lot of information to work. The reason CircuitPython is so simple to use is that most of that information is stored in other files and works in the background. These files are called libraries. 

For example the NeoPixel library allows us to control the NeoPixels on the board. Without importing the library, we cannot access the functionality.

Basic
  • Basic blocks are core functionality of CircuitPython. With these blocks, we can create loops, conditional statements, functions, and more.

Variables
  • This section allows you to create variables. To create a variable, you simply click the Create Variable.. button, give the variable a name and then two blocks will appear which will allow you to use the variable in your code

Digital
  • This library lets us manage digital inputs and outputs. For example this library lets us access the buttons on the CPX and use them to trigger outputs like changing the colors of NeoPixels. Read more about the library here. 

Analog
  • These blocks allow us to interface with the hardware on the board by converting from digital to analog and vice versa. For example if we want to read the voltage of a pin on the CPX we would use this block type. Read about the differences between analog in and out here and here.

Neopixel
  • This library allows us to control the properties of NeoPixels LEDs such as brightness, color and more. Read more here.

Touch
  • With touch blocks, we can access the capacitive touch capabilities of different inputs. On the CPX there are multiple capacitive touch inputs we can use to trigger different events, for example, playing a sound. It's all done with our fingers! Learn more here.

Servo
  • This library allows us to access and control any connected servo motors. Read more here.

Audio
  • Audio blocks allow us to create our own musical tones as well as play sound files. More here.

PWM
  • The PWM (Pulse-Width Modulation) library allows us to control components like leds and servos in a more precise way than just on or off. For example we can fade LEDs and change speed of servos. More here.

Dotstar
  • Control brightness, color and other attributes of another type of led. Dotstars are great for light painting! More here.

Advanced
  • Library for various advanced functionality like controlling data storage.

CPX Easy
  • By clicking "Extentions" on the top right of the interface, we can add one more library entitled "Circuit Playground Easy"
  • This library allows us to perform tasks that the other libraries allow with much simpler code. These blocks are great for first timers. More here.

Tips and Tricks

by Isaac Wellish
circuitpython_Screen_Shot_2019-02-04_at_4.13.34_PM.png

Saving, Loading and Downloading Programs
  • To save a program, click "Save" in the top toolbar. This will automatically place a file entitled "main.xml" into your downloads folder. Rename and save this file somewhere you will remember. 
  • To load old programs, click open in the toolbar and navigate to the .xml file you saved previously.
  • When ready to download programs in CircuitPython format, click Download in the toolbar. This may prompt you to tell your browser if the file is safe to download. Go ahead and click keep and a file called main.py will be downloaded and placed into your downloads folder. Put this file somewhere you will remember. This is the file that will later be put onto the CPX and run the code we wrote.

Switching from CircuitPython Syntax Code to Blocks
  • To switch to CircuitPython syntax-based code, click the Blocks button on the top right of the toolbar.*
  • This will convert the block code into CircuitPython code.
  • Click Python on the right side of the toolbar to go back to code blocks.

 

*This example uses the code from the Analog Demo from Samples in the toolbar.

Copy and Paste

  • Need multiple blocks that are the same? Speed up your workflow by selecting blocks then copy and pasting them!

Using CPX Library with Other Libraries

EduBlocks is still in Beta mode, so it unfortunately doesn't have NeoPixel capabilities yet in the CPX Easy library. Thus to program NeoPixels, we must use the NeoPixel library. 

Knowing this, when we import both the CPX Easy and NeoPixel libraries, we get a "Value: pin in use" error because both libraries are trying to access the NeoPixels.*

To avoid errors like these when using the CPX Easy library, refrain from also using the NeoPixel library.

*This error would show up in the REPL if using a code editor such as Mu. See Troubleshooting section.

Connecting to the CPX

by Isaac Wellish

Now we'll set up the CPX for CircuitPython mode to be able to upload the code we write to the board.

If your CPX is already in CircuitPython mode, double check it is updated  the latest version. You will know you are in CircuitPython mode if the drive CIRCUITPY shows up on your computer when connected via micro usb cable to your computer.

If this is your first time using your CPX with CircuitPython or you see a drive entitled CPLAYBOOT, follow the steps and extended guide below to switch to CircuitPython mode.

  • First install or update CircuitPython. This will give you a .uf2 file.
  • Next, plug the CPX into a computer via micro usb cable and double click the reset button (NeoPixels should turn green).
  • Now drag the recently downloaded .uf2 file onto the CPLAYBOOT drive.
  • The drive should disappear and come back as CIRCUITPY.

Here is an extended guide on how to follow the above steps with images and pictures to help.

If issues are still arising while getting into CircuitPython mode, check out this troubleshooting guide.

Lesson 1: Blinky LED

by Isaac Wellish

Your Circuit Playground Express has a little red LED next to the USB port. It's labeled D13.

In EduBlocks, we are going to turn it on for half a second, then off for half a second, then back on etc. forever!

circuitpython_image.png

The Blinky LED Program
  • First, go ahead and add the CPX Easy block extension if you haven't already. Directions on how to do that are back on the "Block Types" page in the "Navigating EduBlocks" section of this guide.
  • From the Basic block category, drag in import time.
  • FromCPX Easy, import the necessary library by dragging it over.
  • Next in Basic, drag over a while True: loop. This is the main loop of the program and will run forever until the CPX is disconnected from power or reset.
  • Now in CPX Easy, drag in a cpx.red_led block. Set the value in the white bubble to True.
  • Now drag in a time.sleep() block and set the value to 0.5 which will be half a second.
  • Now drag in another cpx.red_led block and set its value to False.
  • Lastly, copy and paste the time.sleep() block from earlier by clicking on it, copying and pasting and dragging under the last block.

Downloading the Program and Uploading to the CPX

Once the blocks look good, click Download in the EduBlocks toolbar.

You may have to tell your browser you want to keep the file if asked. 

A file named main.py should show up in downloads.

With the CPX plugged into the computer, drag main.py to the CIRCUITPY drive.

The drive should now have the file on it and the code should be running!

Is the LED blinking on and off on your CPX?

Issues? Troubleshooting help here.

Here are the code files if you want to upload directly to EduBlocks or the CPX.

EduBlocks file:

CircuitPython Code:

Download: file 
import time
from adafruit_circuitplayground.express import cpx
while True:
  cpx.red_led = True
  time.sleep(0.5)
  cpx.red_led = False
  time.sleep(0.5)

Lesson 2: NeoPixels

by Isaac Wellish

The Circuit Playground Express has two buttons. Button A is on the left and button B is on the right. These buttons can be used as inputs, which means you can use them to tell your board to do something when you press them.

In this example, we'll use the buttons of the CPX to change the colors of the NeoPixels. Button A will turn them red, and B will turn them blue.

circuitpython_image.png

The NeoPixel and Buttons Program

circuitpython_Screen_Shot_2019-02-06_at_6.59.27_PM.png

Library Import and NeoPixel Set Up
  • First import digitalio, board, and neopixel.
  • Next from the NeoPixel category, drag in an np =  neopixel.NeoPixel() block and set it equal to board.NEOPIXEL, 10, brightness = 0.2. This sets up the NeoPixels and determines brightness (can be between 0.0 and 1.0).
  • Now drag in an np = fill() block and set it to (0,0,0). This sets the NeoPixels to the color to black or off.

Creating Variables
  • In order to control the buttons, we need to create some variables to assign to button Aa and button B.
  • To do this, drag in a var block in Basic.
  • In the drop down menu click Rename variable
  • Next name the variable as "button_a" and hit ok.
  • Now you have a variable for button_a!
  • Repeat for button_b

Setting Up the Buttons
  • To set up the buttons, drag in a DigitalInOut() block from the Digital block category. Choose the variable from the drop down menu as button_a. Set the block equal to board.BUTTON_A.
  • Now drag in a .direction = block and set it equal to Direction.INPUT choosing button_a from the drop down menu.
  • Then drag in a .pull = block and set it equal to Pull.DOWN.
  • Repeat the above steps for button_b.

The While Loop:
  • Drag in a while: True loop.
  • Next drag in an ifstatement with the condition set as button_a.value (this block can be found in Digital)
  • From Neopixel drag in np.fill() and set it to (255,0,0) which is Red. (R,G,B)
  • Then drag in an np.show() block.
  • Now put an elif(meaning else if) block setting the condition to button_b.
  • Repeat steps above but set the color to (0,0,255) for blue.

Download the file and drag to the CPX.

Try it out!

When button A is pressed, NeoPixels should turn red.

When button B is pressed they should turn blue!

Here are the code files if you want to upload directly to EduBlocks or the CPX.

EduBlocks file:

CircuitPython Code:

Download: file 
np = None
button_a = None
button_b = None


from digitalio import *
import board
import neopixel
np = neopixel.NeoPixel(board.NEOPIXEL, 10, brightness = 0.2)
np.fill((0,0,0))
np.show()
button_a = DigitalInOut(board.BUTTON_A)
button_a.direction = Direction.INPUT
button_a.pull = Pull.DOWN
button_b = DigitalInOut(board.BUTTON_B)
button_b.direction = Direction.INPUT
button_b.pull = Pull.DOWN
while True:
  if button_a.value:
    np.fill((255,0,0))
    np.show()
  elif button_b.value:
    np.fill((0,0,255))
    np.show()

Lesson 3: Drum Machine!

by Isaac Wellish

This lesson is a spin off of John Park's Drum Machine.

We can use the capacitive touch pads on the Circuit Playground Express as triggers and small .wav files for our drum sounds! 

Until now, we needed to code in CircuitPython to play sound files. Now with EduBlocks, all we need to do is drag a couple of blocks and we're good to go!

First, download the .zip file below, which contains all of the drum samples we'll be using. Save the file to your desktop or somewhere else easy to find, and then unzip it.

You can plug in your Circuit Playground Express, and then drag the drum files onto it. It shows up as the CIRCUITPY drive.

circuitpython_image.png
circuitpython_image.png

EduBlocks Code:

circuitpython_DrumMachineV1.png

Importing Libraries and Defining Variables:
  • Import time, board, touchio, digitalio, and cpx.
  • Create a variable called BPM and set it to .125. This is how fast the drum sounds will play in between each other. In John Park's project the BPM is set to 120 then later on divided by 960 to get the time in seconds that 120 beats per minute is. Unfortunately some math functions are not available in EduBlocks as it is in beta, so we must hard code the value of 120/960 in for our BPM variable. This happens to be .125. Feel free to mess around with this number to try out different drum speeds.

The Touchpads
  • Create 7 variables named touch1, touch2, touch3, ... etc.
  • Drag in 7 =touchioTouchIn() blocks from Touch.
  • Via the drop down menus change to touch1, touch2, touch3, ... etc.
  • Each block should = (board.A1), (board.A2), (board.A3), ... etc.

Trigger the Sounds
  • Drag in a while: True loop.
  • Next drag in an if statement with the condition set as touch1.value (this block can be found in Touch).
  • From CPX Easy, drag in cpx.play_file()and type bd_tek.wav in for the value.
  • Drag intime.sleep() block.
  • Drag variable BPM in as time.sleep() value.
  • Repeat above steps until all 7 sound files are accounted for.

Attach Conductive Materials with Alligator Clips to Capacitive Touch Pads:

circuitpython_image.png

Download the main.py file and drag to the CPX.

Try it out!

Sounds should be triggering when each coin is touched or held!

If you want to use your own sound files, you can! Record, sample, remix, or simply download files from a sound file sight, such as freesample.org. Then, to make sure you have the files converted to the proper specifications, check out this guide here that'll show you how! Spoiler alert: you'll need to make a small, 22Khz (or lower), 16 bit PCM, mono  .wav file!

Want to listen to your Drum Machine at body movin' volumes? No problem! Hook up an 1/8" or 1/4" phono output to the GND and A0 pads, then plug in to an amp or speaker! I tried it on a small speaker with an aux input and it sounded great!

Here are the code files if you want to upload directly to EduBlocks or the CPX.

EduBlocks file:

CircuitPython Code:

Download: file 
touch1 = None
touch2 = None
touch3 = None
touch4 = None
touch5 = None
touch6 = None
touch7 = None

BPM = None


import time
import board
import touchio
from digitalio import *
from adafruit_circuitplayground.express import cpx
BPM = .125
touch1 = touchio.TouchIn(board.A1)
touch2 = touchio.TouchIn(board.A2)
touch3 = touchio.TouchIn(board.A3)
touch4 = touchio.TouchIn(board.A4)
touch5 = touchio.TouchIn(board.A5)
touch6 = touchio.TouchIn(board.A6)
touch7 = touchio.TouchIn(board.A7)
while True:
  if touch1.value:
    cpx.play_file("bd_tek.wav")
    time.sleep(BPM)
  elif touch2.value:
    cpx.play_file("elec_hi_snare.wav")
    time.sleep(BPM)
  elif touch3.value:
    cpx.play_file("elec_cymbal.wav")
    time.sleep(BPM)
  elif touch4.value:
    cpx.play_file("elec_blip2.wav")
    time.sleep(BPM)
  elif touch5.value:
    cpx.play_file("bd_tek.wav")
    time.sleep(BPM)
  elif touch6.value:
    cpx.play_file("bass_hit_c.wav")
    time.sleep(BPM)
  elif touch7.value:
    cpx.play_file("drum_cowbell.wav")
    time.sleep(BPM)

Troubleshooting

by Isaac Wellish

If the code does not work when uploaded to the CPX, you may have to use a code editor and REPL to figure out what's going wrong.

This is a common process in programming known as "troubleshooting" or "debugging".

A code editor and REPL will help you determine which part of your code may be causing errors.

Follow directions on how to download a code editor and troubleshoot issues with the REPL here.

Going Further:

How can you modify the examples from this guide to make even cooler programs with EduBlocks and the CPX? 

One idea could be to trigger different NeoPixel colors when drum sounds are triggered!

The possibilities are endless!

This guide was first published on Feb 05, 2019. It was last updated on Feb 05, 2019.