uber-library-example (community library)

Summary

A simple library that illustrates coding conventions of a Spark Library

Example Build Testing

Library Read Me

This content is provided by the library maintainer and has not been validated or approved.

About

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.

Table of Contents

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

Getting Started

1. Define a function to create library boilerplate

Copy and paste this into a bash or zsh shell or .profile file.

create_spark_library() {
LIB_NAME=$1
echo "creating $LIB_NAME"
mkdir $LIB_NAME
cd $LIB_NAME
mkdir firmware
cat <<EOS > spark.json
{
"name":"${LIB_NAME}",
"version":"0.0.1",
"author":"Someone <email@somesite.com>"
}
EOS
echo '//line 1' > firmware/${LIB_NAME}.h
echo '//line 1' > firmware/${LIB_NAME}.cpp
cat <<EOS > README.md
TODO: Describe your library and how to run the examples
EOS

mkdir firmware/examples
cat <<EOS > firmware/examples/an-example.cpp
// TODO write code that illustrates the best parts of what your library can do
void setup {}
void loop {}
EOS
git init
echo "Tweak the codez, push to GitHub, validate, and publish in the Spark IDE."
echo "Check out https://github.com/spark/uber-library-example for more details"
}

2. Call the function

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.

3. Edit the spark.json firmware .h and .cpp files

• Use this repo as your guide to good library conventions.

4. Create a GitHub repo and push to it

5. Validate and publish via the Spark IDE

To validate, import, and publish the library, jump into the IDE and click the "Add Library" button.

Getting Support

• 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.

The Spark Library Spec

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:

Supporting Files

1. a spark.json meta data file at the root of the library dir, very similar to NPM's package.json. (required)

2. The content of this file is validated via this JSON Schema.

3. a README.md that should provide one or more of the following sections

4. About: An overview of the library; purpose, and description of dominant use cases.
5. Example Usage: A simple snippet of code that illustrates the coolest part about your library.
6. Recommended Components: Description and links to example components that can be used with the library.
7. _Circuit Diagram: A schematic and breadboard view of how to wire up components with the library.

8. Learning Activities: Proposed challenges to do more sophisticated things or hacks with the library.

9. a doc directory of diagrams or other supporting documentation linked to from the README.md

Firmware

1. a firmware folder containing code that will compile and execute on a Spark devce. This folder contains:
2. A bunch of .h and .cpp files constituting the header and source code of the library.
3. The main library header file, intended to be included by users
4. MUST be named the same as the "name" key in the spark.json + a .h extension. So if name is uber-library-example, then there should be a uber-library-example.h file in this folder. Other .h files, can exist, but this is the only one that is required.
5. SHOULD define a C++ style namespace in upper camel case style from the name (i.e. uber-library-example -> UberLibraryExample)
6. The main definition file, providing the bulk of the libraries public facing functionality
7. MUST be named like the header file, but with a .cpp extension. (uber-library-example.cpp)
8. SHOULD encapsulate all code inside a C++ style namespace in uper camel case style (i.e. UberLibraryExample)
9. 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".
10. Other optional .cpp files will be compiled by the Web IDE when the library is included in an app.
11. An examples sub-folder containing one or more flashable example firmware .ino or .cpp applications.
12. 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 like parse-json-and-output-to-serial.cpp.
13. A test sub-folder containing any associated tests

Contributing

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!

Browse Library Files