Using SparkFun Edge Board with Ambiq Apollo3 SDK a tutorial

Available online at:



The SparkFun Edge Development Board is designed to disconnect artificial intelligence capabilities -- such as voice or image recognition -- from the cloud. The idea of performing these computations in a decentralized location (or "edge") is how the board gets its name, but the Ambiq Apollo3 microcontroller is how the Edge gets its power. The Apollo3 is an ultra-low power microcontroller that features an Arm Cortex-M4 core running at 48 MHz but uses only 6 microamps per megahertz. Such a high computational to electrical power ratio can enable machine learning features even in battery powered IoT devices.

SparkFun Edge Development Board - Apollo3 Blue

SparkFun Edge Development Board - Apollo3 Blue


While the Apollo3 has the convenience of support in Arduino, sometimes you want to dig a little deeper and have more control over how you program your board. With that in mind, our goal here is to set up a tool-chain that will give you that finer tuned control.

Required Materials

To follow along with this tutorial, you will need the following materials. You may not need everything, depending on what you have. Add it to your cart, read through the guide, and adjust the cart as necessary.

Serial Terminal

For Windows, you will also want a serial terminal of your choice. A couple options exist such as:

Suggested Reading

If you aren’t familiar with the following concepts, we recommend checking out these tutorials before continuing.

How to Install FTDI Drivers

How to install drivers for the FTDI Basic on Windows, Mac OS X, and Linux.

Serial Terminal Basics

This tutorial will show you how to communicate with your serial devices using a variety of terminal emulator applications.

SparkFun Edge Hookup Guide

Get to know your Edge board, including both the hardware features for you to utilize as well as how to get talking to it.

Bash, Make, and Python -- Oh My

You can learn a lot about embedded software development without ever using command line tools but for brand new systems (like the Apollo3), GUIs and Integrated Development Environments (IDEs) just haven't been built yet. If you're a veteran developer you'll feel right at home. If you're new to this whole idea don't worry -- after you go through this process you'll have a better idea of the steps IDEs take to add convenience. For this tutorial we will standardize our environment so that everyone can follow the same instructions.

Our standardized setup will assume that we are using a Bash shell that has access to Make and Python3.


Bash is a command line tool for unix-like operating systems. Windows users should install one of the several options listed below to emulate bash.

Please note: While the Windows 10 subsystem has support for bash, compilation can be tricky and we do not recommend using this shell.
Running Bash on Windows 10: When you run a cmd window and type bash, it is likely that you'll get the subsystem version of bash. Make sure you use the full path to your installed bash shell when accessing it. For example: ../Program Files/Git/bin/bash.exe


Make is an automated build tool - you give it information about source locations and dependencies and it will automatically call a sequence of commands to compile or re-compile your project based only on the changed files. This can speed up compilation significantly in large projects. Make is a time-tested tool.

Please Note: Going forward be aware of the potential for trouble with backslashes vs. forwardslashes in paths. This tutorial will always use the forwardslash convention, but you may need to use backslashes. Also Windows might require paths to be enclosed in quotation marks if there are spaces or other unusual characters in the path.

Python3 and Packages

Some of the scripts used in the SDK as well as those that upload new code over serial require Python3 and some additional packages.

Note: Another discrepency between *nix and Windows appears: on Windows the exectuable for Python3 is called 'python.exe.' The easiest solution is to rename this to 'python3.exe' after installing the required packages (below).

Things to Note:

With Bash, Make, and Python3 all set up you're good to move on! Fortunately all that foundation laying is the hard part. Next all we need to do is install the compiler toolchain: Ambiq's SDK and the SparkFun Edge Board Support Package.

Toolchain Setup

What is a Toolchain? Well according to Wikipedia:

In software, a toolchain is a set of programming tools that is used to perform a complex software development task or to create a software product, which is typically another computer program or a set of related programs.

Definition courtesy of Wikipedia

The complex task we're trying to solve here is to write an application that can make use of the myriad of features found on the Apollo3 from the comfortable convenience of C or C++. The toolchain that we will construct for this purpose is made up of two main parts:

Later in this tutorial, we will discuss yet another part of the SDK that helps upload your compiled code to the device.

The SDK is just a big file structure filled with harmless source files - it can't help you much on its own. The compiler is a great tool that you can use but without any source files it won't do much more than get mildly irritated. Our goal in this section is to make sure that the two tools are working together seamlessly.

Installing the Compiler

The compiler that we will use is provided by ARM and is thus capable of turning C or C++ code into machine instructions that the Cortex-M4 core can understand. Follow these steps to install the compiler:

GNU-RM Download Site

With the tools installed we will need to make sure that they're accessible from your Bash shell. Here's how:

Restart your Bash shell for the changes to take effect. You can check that you've correctly modified your PATH by entering echo $PATH in the Bash shell. Repeat the test of the tool by entering arm-none-eabi-gcc into the command line. This time the command should be recognized and there should be an error message about 'no source files' instead.

Downloading the SDK

The software development kit (SDK) is a collection of header files and functions that make using the Apollo3 much easier. Rather than reading the 900+ page datasheet and changing bits in registers the SDK gives the user functions and nearly-human-readable constants. On top of that, Ambiq has included a large number of examples to demonstrate all the bells and whistles of the Apollo3.

The SDK is a relatively big collection of files so you won't want to move it around often. You may also want to reference this location when you create a new project so make sure you download this to a location on your computer that makes sense.

This tutorial uses the Ambiq SDK v2.0.0. You can download it from this link, but we recommend getting the latest version here. Alternatively, you can click one of the buttons below:

SDK Version: Ambiq Micro very recently released version 2.1.0 of their SDK, however it is known to be incompatible with some of the examples that we've written for the Edge board. To use our examples please download release 2.0.0. To start work on your own application we'd suggest starting with release 2.1.0. Fortunately it is pretty darn easy to make the changes!

Ambiq Micro Apollo3 Blue SDK Rel2.0.0

Ambiq Micro Apollo3 Blue SDK Rel2.1.0

Ambiq Micro Apollo3 Blue SDK Rel2.2.0

Once you have the SDK downloaded, extract it to your preferred location. Within that location, you should see a folder named something like AmbiqSuite-Rel2.0.0 -- from now on we'll call that the SDK root directory, with the path $AMB_ROOT where AMB expands to something like C:/Users/you/Documents/AmbiqSuite-Rel2.0.0.

SDK Structure: When using an SDK like this one, with 'make' to track necessary compilation, the directory structure is very important. Don't change the locations of files or folders within your SDK. Adding new files or folders is OK.

In the Ambiqsuite-Rel2.0.0 SDK file structure you'll find the primary folders that contain source code that makes it really easy to use the microcontroller - for example drivers for UART, SPI, I2C, GPIO, ADC's -- you name it! You can explore these files in depth if you really need to know how the chip actually works, otherwise it suffices just to know that they are there to support your code-writing efforts.

Adding SparkFun Edge Support

It is very easy to add support for your Edge board to the SDK. Our Board Support Package (BSP) is kept up-to-date in the SparkFun_Edge_BSP Repo on GitHub. Use your favorite method of copying GutHub repos (clone, or download .zip) to put the repo contents under its own folder within the $AMB_ROOT/boards directory. For example my path is $AMB_ROOT/boards/SparkFun_Edge_BSP underneath which are the contents of the repo. The structure is important because the example projects use makefiles with relative paths.


For various and sundry reasons, there are a few housekeeping items that need to be addressed. Please make sure to go through the steps below:

Example Applications

Having arrived here you should have all the components that you need to write an application for the Apollo3:

Coming up next we will look at two example projects. The first will be a basic demonstration of some hardware capabilities like GPIO, UART, ADCs, and I2C communication and it will be pre-configured to build. The second example will be a simple "Hello World" with the main intent of explaining how to set up your own build process.

The examples live in the SparkFun Edge Board Support Package (BSP), which you (hopefully) got while setting up the toolchain. To ensure that the makefile in the first example works be sure to place your copy of the repo in the $AMB_ROOT/boards/ folder. You can achieve the same effect in a number of ways:

Whichever method you choose you should end up with the directory $AMB_ROOT/boards/SparkFun_Edge_BSP that contains the BSP contents.

Get the SparkFun Edge Board Support Package here or by clicking the download link below:

Download the SparkFun Edge Board Support Package (ZIP)

Example: Edge Test

This example will test the hardware features of the Edge board as a starting point to get acquainted with the features of the SDK. The expected behavior of this example is to turn on all four LEDs and transmit data from one microphone and the accelerometer over the serial connection at 115200 baud. When you press Button 14 the loop will break and the board will turn off to conserve power.

If you've followed the rest of this tutorial then getting this example working should require only a few steps. In your Bash shell navigate to $AMB_ROOT/boards/SparkFun_Edge_AmbiqSDK_BSP/examples/example1_edge_test/gcc. This is where the makefile for the gcc toolchain lives. The only change that you should have to make to it to get everything working is to choose the correct serial port.

Now use your favorite text editor to open that file (gcc/Makefile) and replace COM4 with the serial port that your Edge board is connected to (On Windows it will look like COMX, and on Unix-like systems it will be a short string beginning with /dev/cu)

#### Bootloader Configuration
SERIAL_PORT ?= COM4# Or perhaps a Unix-like machine might put '/dev/cu.usbserial-1410' 

Let's make sure that there is a nice area for make to work: enter make clean at the Bash prompt.

Flashing Code to Board

Now to flash your code to the Edge hold down Button 14, press and release reset, and type make bootload into your Bash shell. The process that unfolds should take you through compiling and linking the application, then begin uploading the code.

The uploader script will automatically try to reset the board when it says 'Sending Reset Command,' but if it has trouble it helps to do it manually -- just let go of Button 14 and press reset (some USB-serial bridges seem to work better than others in this scenario). If you have an error like 'could not open port', make sure that the right port is selected and that there are no other serial terminals connected.

Once the code is uploaded, use your favorite serial terminal program to inspect the output (115200 baud).

Try hitting Button 14 to exit the main loop and turn off the board - then press 'reset' to start it up again.

To help guide you to your own exploration of the chip let's look at how we used Ambiq's Hardware Abstraction Layer (HAL) to perform GPIO functions. First off we included am_mcu_apollo.h which in turn includes a whole lot of HAL headers like am_hal_gpio.h. Then we looked through the HAL GPIO header and got a feel for how to use it.

You can explore the HAL in the SDK at $AMB_ROOT/mcu/apollo3/hal to find information about the ADCs, Bluetooth, timers, interrupts, I/O masters (I2C or SPI) and a lot more!

Example: Makefile Project Template

This example will cover what you need to know to start making your own projects on your filesystem and include source and header files of your own for library management. We will go into more detail about what happens when you use make or make bootload.

To get the ball rolling let's look at the first few lines of code in SparkFun_Edge_Project_Template/gcc/Makefile.

# Here are some user modifiable settings. Note that leading spaces are used to separate strings when appending to a variable
TARGET := SparkFun_Edge_Project_Template# this name is the name of the resulting binary file
PROJECT := SparkFun_Edge_Project_Template_gcc

COM_PORT             = COM4
SDKPATH              = # Note that if you copy/paste a windows file path here you need to change backslashes to forward slashes
BOARDPATH            = ${SDKPATH}/boards/SparkFun_TensorFlow_Apollo3_BSP# One day I hope to rename the BSP folder to: SparkFun_Edge_AmbiqSDK_BSP

USER_INCLUDE_DIRS    = -I../src/inc1
USER_INCLUDE_DIRS   += -I../src/inc2

USER_SOURCEDIRS      = ../src
USER_SOURCEDIRS     += ../src/inc1
USER_SOURCEDIRS     += ../src/inc2

USER_MAIN_SRC        = main.c

Here we are declaring, initializing, and sometimes appending to variables that will be known to make when it executes.

The next two variables USER_INCLUDEDIRS and USER_SOURCEDIRS inform the process where to look for files. The include directories are given to the compiler as flags so they are prefixed with '-I'. The source directories tell make where to look for source files that the user wants to compile. In both cases the append operation '+=' is used to add more lines. It is important to include a space after the '=' sign so that all your paths remain separated.

The last two variables USER_MAIN_SRC and USER_SOURCE_FILES are used to create a list of all the files to compile.

The above variables are all that you should need to set up to have a successful build. You can try it out by making sure you're in the directory SparkFun_Edge_Project_Template/gcc and then entering make into the command prompt. If there are no errors then the /bin directory will contain a '.bin' file with the name that you chose for the TARGET variable. Entering make bootload with Button 14 held down, and hitting reset once prompted, should get your code on the board.

Now let's take a moment to explore the highlights of what exactly gets done with those variables that you defined. A little way down the prefix of compiler executables is listed as a variable along with other values to give t the compiler in the PART, CPU, and FPU flags. Then the suite of suffixes for C / C++ compilation, linking, and other toolchain elements are given short easy names like CC, GCC, CPP, and LD. After this the included directories and files that you defined at the top are combined with those coming from the SDK. Near the end, the makefile automatically assembles a list of recipes that explain the dependencies in the build process. To wrap it all up the makefile actually spits out the commands required to build the executable (.bin) into the shell. As a cherry on top if you used 'make bootload' then it will also create an Over The Air (OTA) image blob, convert it to a wire update blob, and then begin the serial upload process using a few Python scripts.

Now, go boldly into development for this powerful new microcontroller armed with the knowledge of exactly how your application gets from a smattering of source code to a lean mean machine-code package.


Getting started with an advanced development board like the Edge can be difficult. Especially with this process it is easy to get off into the weeds. The first steps to troubleshooting should always be to carefully re-check the work you've done. Pretend you're explaining what you're doing to your grandmother. If that doesn't work then try checking out the Edge Troubleshooting thread on the SparkFun Forums.

SparkFun Edge Forum

Resources and Going Further

Congratulations! If everything went according to plan then you've run an example on the Edge board and you are now all set up to start building your own applications. Here are a few resources to help guide that process and explain more about the topics covered in the tutorial.

Tutorial Links:

Want more information on the Ambiq Apollo3 or the SparkFun Edge Board?

Need some inspiration for your next project? Check out some of these tutorials!


SparkFun Edge Hookup Guide

Get to know your Edge board, including both the hardware features for you to utilize as well as how to get talking to it.

Artemis Development with Arduino

Get our powerful Artemis based boards (Artemis Nano, BlackBoard Artemis, and BlackBoard Artemis ATP) blinking in less than 5 minutes using the SparkFun Artemis Arduino Core!

Hookup Guide for the SparkFun RedBoard Artemis

Get started with the RedBoard Artemis - all the functionality of the SparkFun Artemis module wrapped in the familiar Uno footprint

Hookup Guide for the SparkFun RedBoard Artemis ATP

Get started with the RedBoard Artemis ATP - all the functionality of the SparkFun Artemis module wrapped in the Mega Arduino Footprint | CC BY-SA 3.0 | SparkFun Electronics | Niwot, Colorado