Using SparkFun Edge Board with Ambiq Apollo3 SDK
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.
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:
- Software Development Kit (SDK): a smorgasbord of useful software definitions that are specific to the microcontroller
- Compiler: turns the SDK code into the specific machine language that the Apollo understands.
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:
- Visit the GNU-RM Download Site and scroll down to download the proper installer for your system (for Windows you will need one with the SHA extension). Alternatively, click the button below to be redirected to the download page:
- Run the installer -- if you get a warning from your OS dismiss it because you trust ARM. (You do trust ARM... don't you?)
- If there is an option to add the tools to your PATH choose that. If there is not then pay extra close attention to the install directory -- you'll need to make sure the directory that contains your tools is included in your PATH system variable.
- Complete the installation
With the tools installed we will need to make sure that they're accessible from your Bash shell. Here's how:
- Enter arm-none-eabi-gcc into Bash to verify whether you have access to the tool. If a 'command not found' or similar error occurs then proceed with adding the tool to your path. Make sure that you know where the tools were installed. For example the default location on Windows is something like C:/Program Files (x86)/GNU Tools ARM Embedded/8 2018-q4-major/bin. This is what you need to add to your PATH.
- Unix, Linux, or similar: 'How to permanently set $PATH on Linux/Unix?' on StackOverflow
- Mac OS X: Here's a good concise example of how to 'Add to the Path On Mac OSX'
- Windows: Here's a great tutorial for editing the PATH on many versions of Windows
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.
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.
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.
- $AMB_ROOT/boards : Here you can add custom definitions of the hardware or software capabilities of a given board that you might write code for - instead of having to manually include a custom header file all over the place. Ultimately this is where the SparkFun Edge Board Support Package will be placed.
- $AMB_ROOT/CMSIS - This is a unified set of instructions for cortex processors.
- hal: Here you'll find the Ambiq interfaces for the hardware peripherals on the board.
- apollo3_scripts: Python scripts for making and transmitting update images
- $AMB_ROOT/utils: Utilities that aren't related to hardware peripherals - delays, string operations, etc...
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:
- Within the Ambiq SDK, there is an incorrectly named file. Rename /tools/apollo3_scripts/keys_info0.py to /tools/apollo3_scripts/keys_info.py.
- Permissions on bsp/tools/uart_wired_update_sparkfun.py may be incorrect. Make sure to change the permissions on this file to 755. (ie: chmod 755 uart_wired_update_sparkfun.py)