Powered by GitBook

Spark Basics: First Steps and Examples

connect me to the internets please

We connected your device to the internet in the first lesson using your phone, but this isn't the only way to connect. Here's an important reference on how to get your device online in other ways, namely, with the command line interface (Spark CLI). If you're already connected and really eager to get going, skip to the second part of this lesson or write a blinking program in the lesson after that.

Blueprint 002: Connecting with the Spark CLI

Connect your Core or Photon using Spark CLI, the command line interface. Perfect Blueprint to use if you can't get it online using the phone application in Blueprint 001: Getting Started.

Materials

  • Hardware
    • Core or Photon
    • USB to micro USB cable
    • Computer
  • Software
  • Knowledge
    • Terminal/command line super-basics
      • Nothing fancy. If you know how to access your command line, you're all set.

Step One: Downloading the Command Line Interface

First make sure you have node.js installed. Then open your command prompt or terminal and enter:

npm install -g spark-cli
spark cloud login

Once that is done, upgrade to the latest version using:

npm update -g spark-cli

Step Two: Connect Your Core Using Serial

Make sure your core is plugged into the USB port on your computer. Make sure it is blinking blue (looking for wifi networks). If it is blinking green instead, this means it is trying desperately to connect to a network. You can wait to see if it blinks cyan, or you can hold the MODE button for ten seconds until it blinks blue again.

If you have never connected your core before, then the following will walk you through the process:

spark setup

Note that it will ask you to enter your login credentials. If you don't have a login yet, create one at spark.io/build.

If you have connected in the past, you can connect your core by typing:

spark serial wifi

This will instruct you on how to connect over serial.

What is Serial?

Serial communication is used to send information over USB between a microcontroller and another chip or computer. In this lesson, we are sending wifi credentials to your device over USB. Once it learns this information, it will be drawing power and not information via USB.

Now you're connected! Your core is online and listening to the network. You can feel free to skip the next step, or if you want to play with the CLI some more, keep reading!

If you have not yet flashed firmware to this device, then the tinker functions are accessible for you to call through the command line. To see what functions are available currently on your device, type:

spark list

The output will probably look something like this:

Checking with the cloud...
Retrieving cores... (this might take a few seconds)
my_core_name (0123456789ABCDEFGHI) is online
  Functions:
    int digitalread(String args) 
    int digitalwrite(String args) 
    int analogread(String args) 
    int analogwrite(String args)

The number after your core's name is your core ID. If you have multiple cores on your account, these will be listed too. spark list will also inform you of which cores are online and offline.

Wait, in the smartphone app and in the development environment, it says digitalWrite, not digitalwrite. Are these the same thing?

Yes. It's just a stylistic thing. When we are in the development environment, we use digitalWrite() because that is standard formatting for this purpose. When you call a Spark function over the internet, you are posting to a URL, and it is standard formatting to have this be in lowercase.

Using the function digitalwrite, you can set the D7 LED to high over the command line. Make sure you know your core ID (shown after your core name when you spark list, and type the following:

spark call 0123456789ABCDEFGHI digitalwrite D7,HIGH

This function should return a 1 to your command line prompt and you should see the D7 LED turn on. Awesome, right? You can turn it off using 

spark call 0123456789ABCDEFGHI digitalwrite D7,LOW

Yayyy!! You blinked a light from the command line!

Using spark call and tinker, you can communicate with any of the pins, not just with the D7 LED. You can wire things to the pins to run motors, read sensors, and much more. The real fun part comes when you write your own firmware, of course. We'll go over that in the next sections.

If you want to learn more about the Spark CLI, it's awesome and totally helpful. Documentation is here.

onwards to development!

Bored with Tinker? Put your own firmware on your device.

Now that you've connected your device, it's time to put new firmware on it. We'll review how to use the development environment and go over some of the fun things you can put into Spark's firmware.

You can write firmware for your device using the online development environment found at spark.io/build. Go through this guide to learn about the development environment.

If you prefer, you can also download Spark Dev, the local development environment. Documentation for Spark Dev can be found here.

Building with Spark

A fun way to go through building with Spark is to follow the examples in the documentation. But here's a brief overview of the development environment to get you started.

Go to docs.spark.io/build and follow the instructions to set up and get familiar with the online development environment. It goes over everything in much more detail. Here's a quick cheat-sheet on the icons, in case you forget:

flash Flash Send, or "flash," your selected firmware to your selected device.

verify Verify Check your code for errors without actually sending it to your device. A good opportunity to see if your code will compile properly and fix bugs without running the entire upload process.

save Save Save your work to your account without flashing or verifying.

code Code See your current code, edit your code, rename your firmwares, select examples to use.

libraries Libraries Search and select helpful libraries to use in your code.

docs Docs A link to Spark's documentation.

cores Cores A list of all your devices. See which ones are online, select the one to which you might want to flash new firmware. This section also shows you your device IDs.

settings Settings Change your pasword, log out, see and reset your access token.

Now I want to write something. How do I do that?

Spark's development environment uses Wiring, the same programming language used for Arduino. I won't go into detail about Wiring, but here are some basics.

There are two sections that need to be included in every Wiring program: setup and loop. These are defined for you when you create a new program in the development environment.

Setup

void setup() defines a function that will be executed when your device powers on. This usually includes setting the pins as inputs or outputs and defining URLs through Spark.function()

Loop

void loop() defines a function that will be run over and over again, indefinitely, after your device runs void setup(). If you wanted your LED to blink indefinitely, for example, you might tell it to turn on and then off in void setup().

Outside of Loop and Setup

You can define global variables and separate functions outside of loop and setup. Note that you don't have to put anything in void loop() if a loop is not necessary for your project. The RC car example shows this in its use of Spark.function(), where the loop is left empty.

Wait, I don't get it.

To get a basic idea of loop and setup, check out the "Blink an LED" example at spark.io/build at the bottom of the code sidebar. It has a lot of awesome comments to help you understand what is going on. Important functions used in this code are:

Check out the RC Car Example as well for an idea of how we can control our devices using Spark.function(). When you are ready, move on to the next section to get a better idea of how Spark devices communicate with the cloud. Blueprint