B-3 New App Template

Let's title your new app template, and learn about the basic code structure for Photon device apps.

Title Your App

In the Code menu panel, you'll notice that your current app doesn't have a title yet.

It's recommended to give each app a unique title. Particle Build will allow you to save different apps that have the same title – but this could get confusing, so try to use unique app titles.

NOTE: You cannot have any blank spaces in an app's title. If you want to visually separate words in your app's title, just use a hyphen or an underscore.

Enter hello-world as your app's title.

You'll see the app's title show up in the "My Apps" list.

HOW TO RENAME APP: If you wanted to change the title of your current app, just click the title to enter a different title.

Photon App Structure

Your code editor should show the basic structure for a new Photon device app:

void setup() {

}

void loop() {

}

Setup Function

Every Photon device app must have one (and only one) setup() function. You can add lines of code between this function's opening and closing curly braces.

The setup() function will run one time when your app first starts (which is when your Photon is first powered on – or is restarted using its Reset button).

The code added within the setup() function typically sets pin modes for the device's inputs and outputs, initializes settings for certain inputs and outputs, or performs other "setup" actions that need to occur at the start of the program.

Even if you didn't add any code within the setup() function, your app must still have this function.

Loop Function

Every Photon device app must have one (and only one) loop() function. You can add lines of code between this function's opening and closing curly braces.

After the setup() function is done running, the loop() function will start to run. When all the code within the loop() function has been performed, the loop() function will automatically run itself again. It keeps running in an endless loop (until the device is restarted or powered off).

The code added within the loop() function performs the main tasks of your program.

Even if you didn't add any code within the loop() function, your app must still have this function.

VOID: Why is void listed before the setup() and loop() functions? This is because each function in your Photon device app must declare a data type (such as: integer, boolean, etc.) for the data value returned by the function. In this case, void indicates the function does NOT return any data value.

Other Sections of App

Besides having the required setup() and loop() functions, your Photon device apps will typically have some or all of the following:

• Comments

• Libraries

• Global Variables

• Custom Functions

Comments

Comments are optional notes that you can insert to help explain or clarify portions of the code to anyone reviewing the program. Comments can be single-line or multi-line blocks.

Any comments in the app are ignored when the program is compiled and uploaded to your device.

// Comments are notes to yourself or others reading your code
// Each single-line comment starts with two forward slashes
​
/*
A multi-line comment block starts with a forward slash and asterisk
You can include as many lines of notes in the block as you need
A multi-line comment block ends with an asterisk and forward slash
*/

Libraries

Some device apps might include (i.e., import) one or more library files. A library is a file of pre-built code that provides additional functions that your program can utilize. For example, certain inputs and outputs have their own code library with functions to make it easier to control the input or output.

Particle Build has a Libraries menu where you can search for existing libraries (or upload your own library file that you've created). When you select a library to be added to your app, Particle Build will automatically insert an #include statement for the library at the beginning of your app code.

Global Variables

Your device app will typically have code that declares global variables which store data used in your program's functions, such as pin numbers for sensors, etc.

Global variables are usually listed before the setup() function (to make it easier to read the code).

Custom Functions

You can also add your own custom functions to your device app. Each custom function must have a unique function name.

Custom functions are used to contain code that performs specific tasks or subtasks. Custom functions are optional, but they can help break up your code into smaller modules that are easier to understand (and easier to re-use). So rather than listing all your main program code within the loop() function, you can subdivide some or all the code into custom functions.

The code within a custom function is only run if and when that custom function is "called" (by listing the function's name) within the setup() or loop() function. A custom function can also be "called" within another custom function.

Custom functions are usually listed after the loop() function (to make it easier to read the code).