Setup Adafruit Feather M4 for CircuitPython

Your Adafruit Feather M4 should already come with CircuitPython but maybe there's a new version, or you overwrote your board with Arduino code! In that case, see the below for how to reinstall or update CircuitPython. Otherwise you can skip this and proceed with the build.

CircuitPython Libraries

Install the following Adafruit libraries for Circuit Python by downloading the latest bundle. Unzip the file and locate the needed libraries. Drop the libraries into a folder named "lib" on the CIRCUITPY drive.

Required CircuitPython Libraries:

  • adafruit_bus_device
  • adafruit_ds3231
  • adafruit_motor
  • adafruit_register
  • neopixel.mpy

Before continuing make sure your board's lib folder or root filesystem has the library files copied over.

Download code bundle

The full code listing is available here

You can download all the project source code by clicking below, it even includes the WAV file!


When the time is 11:59, the continuous rotation servo slowly turns and lowers the ball. A 10-second countdown audio file plays over the speaker while neopixels cycle through colors. "Auld Lang Syne" plays after the countdown while neopixels display a show of firework effects.

If you want a more in-depth explanation of how this project works, check out Dave Astel's guide on CircuitPython state machines. It goes into a lot more detail of how he got this code structured and working!

Audio Files

Two separate audio wave files are used. The main song file name is "Auld_Lang_Syne.wav" – This audo can be changed, just make sure the code reflects any file name changes. The crowd cheering audio file name is "countdown.wav" likewise, can be changed.

Original audio sources:

Test/Reset Mode

A momentary pushbutton can be used to trigger the servo and run through the states. This is used to trip the ball drop for on-demand testing.

  • Single press will activate the countdown followed by song with fireworks.
  • Press to pause while sequence is running. Press again to resume.
  • 2-second press and hold will activate reset mode turning servo to wind up ball with rope.

Setting The Time

The time must be set on line 87 – This sets up the initial time in the internal clock. Follow the comments above for year, month, day, minute, etc. Use the test_trigger function on line 288 to adjust the trigger time – This is when the ball drops.

For testing the RTC, we set the trigger time 10 seconds before the initial time to trip the ball drop shortly after powering on the circuit.

Adjust the values in the code to reflect your desired trigger time.

Download: file
t = time.struct_time((2018,  12,   31,   23,  58,  55,    1,   -1,    -1))
Download: file
if test_trigger or (t.tm_mday == 31 and
    t.tm_mon == 12 and
    t.tm_hour == 23 and
    t.tm_min == 58 and
    t.tm_sec == 45):

Modify Parameters

Common parameters to tweak are the number of pixels, ball drop speed, and duration. Read the comments in the code to see more.

Download: file
# Implementation dependant things to tweak
NUM_PIXELS = 78               # number of neopixels in the striup
DROP_THROTTLE = -0.03         # servo throttle during ball drop
DROP_DURATION = 10.0         # how many seconds the ball takes to drop
RAISE_THROTTLE = 0.1         # servo throttle while raising the ball
FIREWORKS_DURATION = 30.0    # how many second the fireworks last

Upload The Code

Copy and paste the code below into a new text document (we recommend using Mu as your editor, which is designed for CircuitPython.). Save the file and name it as

Once the files has been uploaded to the drive, the board will automatically reboot and run the code.

In order for the code to function properly, the FeatherWings must be connected to the Feather M4 via the Triper FeatherWing or similar.
This guide was first published on Dec 29, 2018. It was last updated on Dec 29, 2018. This page (Software) was last updated on Jan 15, 2020.