This repo serves as the specfication for what constitutes a valid Spark firmware library and an actual example library you can use as a reference when writing your own libraries.
Spark Libraries can be used in the Spark IDE. Soon you'll also be able to use them with the Spark CLI and when compiling firmware locally with Spark core-firmware.
This README describes how to create libraries as well as the Spark Library Spec.
The other files constitute the Spark Library itself:
- file, class, and function naming conventions
- example apps that illustrate library in action
- recommended approaches for test-driven embedded development
- metadata to set authors, license, official names
Copy and paste this into a bash or zsh shell or .profile file.
create_spark_library() {
LIB_NAME="$1"
# Make sure a library name was passed
if [ -z "{$LIB_NAME}" ]; then
echo "Please provide a library name"
return
fi
echo "Creating $LIB_NAME"
# Create the directory if it doesn't exist
if [ ! -d "$LIB_NAME" ]; then
echo " ==> Creating ${LIB_NAME} directory"
mkdir $LIB_NAME
fi
# CD to the directory
cd $LIB_NAME
# Create the spark.json if it doesn't exist.
if [ ! -f "spark.json" ]; then
echo " ==> Creating spark.json file"
cat <<EOS > spark.json
{
"name": "${LIB_NAME}",
"version": "0.0.1",
"author": "Someone <email@somesite.com>",
"license": "Choose a license",
"description": "Briefly describe this library"
}
EOS
fi
# Create the README file if it doesn't exist
if test -z "$(find ./ -maxdepth 1 -iname 'README*' -print -quit)"; then
echo " ==> Creating README.md"
cat <<EOS > README.md
TODO: Describe your library and how to run the examples
EOS
fi
# Create an empty license file if none exists
if test -z "$(find ./ -maxdepth 1 -iname 'LICENSE*' -print -quit)"; then
echo " ==> Creating LICENSE"
touch LICENSE
fi
# Create the firmware/examples directory if it doesn't exist
if [ ! -d "firmware/examples" ]; then
echo " ==> Creating firmware and firmware/examples directories"
mkdir -p firmware/examples
fi
# Create the firmware .h file if it doesn't exist
if [ ! -f "firmware/${LIB_NAME}.h" ]; then
echo " ==> Creating firmware/${LIB_NAME}.h"
touch firmware/${LIB_NAME}.h
fi
# Create the firmware .cpp file if it doesn't exist
if [ ! -f "firmware/${LIB_NAME}.cpp" ]; then
echo " ==> Creating firmware/${LIB_NAME}.cpp"
cat <<EOS > firmware/${LIB_NAME}.cpp
#include "${LIB_NAME}.h"
EOS
fi
# Create an empty example file if none exists
if test -z "$(find ./firmware/examples -maxdepth 1 -iname '*' -print -quit)"; then
echo " ==> Creating firmware/examples/example.cpp"
cat <<EOS > firmware/examples/example.cpp
#include "${LIB_NAME}/${LIB_NAME}.h"
// TODO write code that illustrates the best parts of what your library can do
void setup {
}
void loop {
}
EOS
fi
# Initialize the git repo if it's not already one
if [ ! -d ".git" ]; then
GIT=`git init`
echo " ==> ${GIT}"
fi
echo "Creation of ${LIB_NAME} complete!"
echo "Check out https://github.com/spark/uber-library-example for more details"
}
create_spark_library this-is-my-library-name
- Replace
this-is-my-library-name
with the actual lib name. Your library's name should be lower-case, dash-separated.
- Use this repo as your guide to good library conventions.
To validate, import, and publish the library, jump into the IDE and click the "Add Library" button.
- Check out the libraries category on the Spark community site and post a thread there!
- To file a bug; create a GitHub issue on this repo. Be sure to include details about how to replicate it.
A Spark firmware library consists of:
- a GitHub REPO with a public clone url
- a JSON manifest (
spark.json
) at the root of the repo - a bunch of files and directories at predictable locations (as illustrated here)
More specifically, the collection of files comprising a Spark Library include the following:
-
a
spark.json
meta data file at the root of the library dir, very similar to NPM'spackage.json
. (required) -
The content of this file is validated via this JSON Schema.
-
a
README.md
that should provide one or more of the following sections
- About: An overview of the library; purpose, and description of dominant use cases.
- Example Usage: A simple snippet of code that illustrates the coolest part about your library.
- Recommended Components: Description and links to example components that can be used with the library.
- _Circuit Diagram: A schematic and breadboard view of how to wire up components with the library.
- Learning Activities: Proposed challenges to do more sophisticated things or hacks with the library.
- a
doc
directory of diagrams or other supporting documentation linked to from theREADME.md
- a
firmware
folder containing code that will compile and execute on a Spark device. This folder contains: - A bunch of
.h
,.cpp
, and.c
files constituting the header and source code of the library. 1. The main library header file, intended to be included by users- MUST be named the same as the "name" key in the
spark.json
+ a.h
extension. So ifname
isuber-library-example
, then there should be auber-library-example.h
file in this folder. Other.h
files, can exist, but this is the only one that is required. - SHOULD define a C++ style namespace in upper camel case style from the name (i.e. uber-library-example -> UberLibraryExample) 2. The main definition file, providing the bulk of the libraries public facing functionality
- MUST be named like the header file, but with a
.cpp
extension. (uber-library-example.cpp) - SHOULD encapsulate all code inside a C++ style namespace in upper camel case style (i.e. UberLibraryExample)
3. Other optional
.h
files, when included in a user's app, will be available for inclusion in the Web IDE via#include "uber-library-example/SOME_FILE_NAME.h"
. 4. Other optional.cpp
files will be compiled by the Web IDE when the library is included in an app (and usearm-none-eabi-g++
to build). 5. Other optional.c
files will be compiled by the Web IDE when the library is included in an app (and usearm-none-eabi-gcc
to build).
- MUST be named the same as the "name" key in the
- An
examples
sub-folder containing one or more flashable example firmware.ino
or.cpp
applications. 1. Each example file should be named descriptively and indicate what aspect of the library it illustrates. For example, a JSON library might have an example file likeparse-json-and-output-to-serial.cpp
. - A
test
sub-folder containing any associated tests
This repo is meant to serve as a place to consolidate insights from conversations had about libraries on the Spark community site, GitHub, or elsewhere on the web. "Proposals" to change the spec are pull requests that both define the conventions in the README AND illustrate them in underlying code. If something doesn't seem right, start a community thread or issue pull requests to stir up the conversation about how it ought to be!