Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
You'll add a variable in your app code to represent the built-in LED light.
Your "Hello World" app will make the Photon's built-in blue LED light turn on and off in a blinking pattern. This will be accomplished by sending separate "on" and "off" signals to the LED's pin.
Each I/O pin on the Photon circuit board is identified by a pin number (such as: A0, A1, A2, D0, D1, D2, etc.). In this case, the Photon's built-in blue LED light is connected to pin D7 (via internal circuitry).
When coding a Photon device app, you will typically create a global variable to store a pin number for each input or output connected to your Photon. This will help make your code easier to understand because the variable names help identify each input or output.
You'll need to create a global variable to store the pin number of the built-in LED. Add this code statement to your app by inserting it (as a separate line of code) before the setup() function:
HOW TO COPY CODE: When using this IoT code guidebook, you can copy a code block simply by clicking the copy icon displayed in the upper right of the code block.
This code statement does 3 things (in order):
It declares a data type for the variable's value. In this case, int stands for integer (whole number). Photon pin numbers are always treated as int values (even though they have letters).
It declares the variable's name. In this case, the variable will be called LED. You get to decide what to name your variables. Choose names that will make sense to anyone reviewing your code.
It assigns a value to the variable. In this case, the variable's value will be equal to D7, which is the pin number for the Photon's built-in LED light.
Notice that this code statement ends with a semi-colon. Typically, each code statement in your app will end with a semi-colon. The semi-colon separates code statements, similar to how periods separate sentences in written English.
The exceptions to ending with a semi-colon are certain statements (such as functions, conditionals, loops, etc.) that use curly braces to enclose other code statements. However, within the curly braces, each code statement ends with a semi-colon.
Although you can actually list multiple code statements on the same line (because their semi-colons will separate them), each code statement is traditionally listed on its own separate line to make it easier to read the code.
The Particle Build code editor does NOT autosave your work as you type, so be sure to periodically save your code.
Save your app code by clicking the Save icon in the left navigation bar.
You get to decide what to name each variable in your app's code. However, here are a few rules and recommendations to help you name your variables:
Each global variable must have a unique name.
A variable's name cannot be one of the keywords in the Wiring programming language.
Variable names must be one word (no spaces allowed).
Variable names can contain lowercase letters, uppercase letters, numbers, and certain special characters (such as underscores, etc.) – but the name cannot start with a number.
Make each variable's name concise yet descriptive, so it will be easy to read and understand.
Example of variable name that's concise yet descriptive: button
Example of variable name that's too concise: b
Example of variable name that's too descriptive: greenbuttonthatturnslighton
If your variable name combines multiple words, you can make the name easier to read by either using an underscore between words – or using "camelCase" (lowercase letters, but new words start with an uppercase letter).
Examples of variable names using underscores: red_light, motion_sensor
Examples of variable names using camelCase: redLight, motionSensor
If you have multiple inputs or outputs of the same type (multiple LED lights, multiple buttons, etc.), add an adjective or number to their variable names to help identify them in your app code.
Examples of variable names with adjectives: redLED, blueLED
Examples of variable names with numbers: button1, button2
Let's start your Photon to verify it connects to Wi-Fi and Particle Cloud.
Start your Photon by powering on the circuit board:
Connect a power cable into the barrel jack or Micro-USB port on the circuit board, and connect the other end of the cable to a power source (such as: battery, computer USB port, etc.).
CHOOSE ONE: Only one power source (barrel jack or Micro-USB) needs to be connected.
REMINDER: The Photon circuit board does not have an "on/off" switch. As soon as a power source is connected to its barrel jack or Micro-USB port, the Photon will power on and start running. To turn off the Photon, you have to disconnect its power source.
Once the circuit board has power, you should see its red Power LED light turn on.
You should also see the RGB LED light turn on – it will blink green while the Photon automatically tries to connect to Wi-Fi.
Once the Photon has successfully connected to Wi-Fi and Particle Cloud, the RGB LED will be cyan (light blue) and "breathing" (slowly blinking).
CONNECTION ISSUES: If your Photon is having issues (can't connect to Wi-Fi, etc.), you'll see a (such as: breathing green, breathing pink, etc.). You may have to consult with your teacher to troubleshoot your device.
When your Photon is powered on (or restarted), it will automatically try to connect to a Wi-Fi network. It does this by using its saved list of Wi-Fi logins (network names and passwords). Every Photon can be programmed to store login information for up to 5 different Wi-Fi networks.
A brand new Photon will not have any Wi-Fi logins saved yet. However, the Photon provided to you by your teacher will most likely already have a Wi-Fi login programmed into it.
Once your Photon is connected to Wi-Fi, the Photon will automatically try to connect to Particle Cloud, which is a cloud service that Particle provides for all of its microcontroller devices. All of your Photon's internet communications are routed through Particle Cloud.
Particle Cloud can be used to:
Code and store all your different Photon device apps (using Particle Build code editor)
Update the app stored on your Photon device
Update the firmware on your Photon device
Send and receive data between your Photon device app and your web app
Manage your Photon device remotely
Let's title your new app template, and learn about the basic code structure for Photon device apps.
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.
Your code editor should show the basic structure for a new Photon device app:
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.
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.
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
Any comments in the app are ignored when the program is compiled and uploaded to your device.
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.
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).
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).
In this second tutorial, you'll program a "Hello World" app for your IoT device.
The goals of this second tutorial are to help you:
Verify your Photon device connects to Wi-Fi and the Particle Cloud service
Understand how to use Particle Build to create Photon device apps
Create a Hello World app to learn how to program your Photon device
When learning a new programming language, the first step that many people take is to create what is called a program. Traditionally, this program simply displays the text "Hello World" on the screen and only requires a few lines of code. The purpose is to demonstrate that you can create a simple yet functional program in the new coding language. It's the first step before creating more complex programs.
However, your Photon circuit board does not have a built-in screen. Your Photon kit does have a micro OLED screen that can be connected to the Photon – but that would require connecting 7 different jumper wires and coding a more complex app. Eventually, you'll be able to do this – but we need something much simpler for your first Photon app.
The good news is your Photon circuit board has a built-in blue LED light (D7) that can be controlled by your device's app. You won't have to connect any extra parts or wires yet – and you can program a simple app that makes the built-in LED blink on and off repeatedly, as a way of saying "Hello World."
All the apps that run on your Photon device will be coded using Particle's version of the open-source programming language framework for microcontrollers.
The on your Photon runs a modified version of the Wiring language with a few minor differences, as well as some additional methods (functions) customized for the Photon hardware.
One example of a minor difference:
In the original Wiring language, the analogRead() method reads the value of an analog input pin and returns the value as an integer (whole number) between 0-1023.
In the Particle firmware, the analogRead() method does the same thing but returns the value as an integer between 0-4095 (providing a higher level of precision).
The Particle firmware contains additional methods (functions) that are not part of the original Wiring language. For example, there are methods which are used to make the Photon interact with Particle Cloud. There are methods which can be used to control built-in hardware components on the Photon circuit board (such as the Wi-Fi module, RGB light, etc.).
WIRING VS. C++: Wiring (like Arduino) is a programming framework written in C++, so you can also directly incorporate C++ code within your device app.
Now that your Photon is connected to Wi-Fi and Particle Cloud, your team will log in to Particle Build, the code editor that will be used to create your "Hello World" app.
Particle Build is an online code editor (web IDE) provided by Particle. Particle Build is part of the Particle Cloud platform. You will use Particle Build to code and store all your Photon device apps.
The Photon device itself can only store and run one app at a time. However, you can create and save multiple apps in Particle Build. When you need to update the specific app stored on your Photon device, you'll do this in Particle Build – and your Photon will download the new app over Wi-Fi.
Your team will need a Particle account to log in to Particle Build. However, your teacher will most likely provide your team with an existing Particle account login (email & password) that's already associated with your specific Photon device. Every Photon has a unique device ID it uses to communicate with Particle Cloud, and each device ID can only be associated with one Particle account.
One person on your team should log in to using your team's Particle account login.
Once you're logged in, you'll see the Particle Build code editor, which defaults to the "Code" menu and shows a blank app template.
The user interface for Particle Build is divided into 4 sections:
On the far left is a vertical navigation bar with icons.
On the middle left is a menu panel showing options for the current navigation selection.
On the right side is the code editor panel showing the code for your current app.
On the bottom of the code editor panel is a horizontal status bar that displays messages.
If you hover your mouse pointer over an icon in the navigation bar, the icon's name will be displayed. Here is a summary of the navigation icons from top to bottom:
The middle menu panel can be toggled between "show" and "hide" by clicking the same navigation icon repeatedly.
In the left navigation bar, click the Code icon.
The middle menu panel will become hidden.
Click the Code icon again to show the menu panel again.
In general, you'll probably want to keep the menu panel shown – but if you want extra space for your code editor panel, you can temporarily hide the menu panel.
In the left navigation bar, click the Devices icon.
The middle menu panel will list your Particle devices. You should see a device name listed under P1 (because your device is a Photon P1). Your device's connection status is shown as a colored dot to the right of its name. If your device is connected to Wi-Fi and Particle Cloud, the dot should be cyan (light blue) and "breathing" (slowly blinking) – just like the RGB LED on your Photon circuit board.
Click the drop-down arrow to the right of the device's connection status dot. This will show additional information about your device:
You'll see the device ID, which is a unique ID used by your device to interact with Particle Cloud. Later when you create web apps to interact with your device, you'll need your device ID.
You'll see the firmware version that is currently saved on your device. If an updated version is available, your device's firmware will be automatically updated the next time you flash an app.
If you wanted to double-check your device and its connection (imagine you had multiple devices), an easy way is to signal it from Particle Build.
Click the Signal button. Particle Cloud will send a signal to your device over Wi-Fi. Your Photon's RGB LED will respond by cycling through a rainbow of colors.
Click the button again to stop signaling your device. Your Photon's RGB will return to breathing cyan.
In the left navigation bar, click the Code icon to return to your list of apps.
Next you'll flash your "Hello World" app to your Photon device to run the app.
Be sure your Photon is powered on and connected to Wi-Fi and Particle Cloud.
Flash your app code to your Photon device by clicking the Flash icon in the left navigation bar. (Particle Build will first save and verify your code before flashing it.)
Your Photon will download the app from Particle Cloud over Wi-Fi and store the app in your Photon's flash memory. While this is occurring, you should see that the RGB light on your Photon's circuit board will blink pink.
Once the download is complete, your Photon will automatically restart itself. You'll see the RGB light on your Photon blink green while it tries to reconnect to Wi-Fi. Once your Photon has reconnected to Wi-Fi and Particle Cloud, the RGB will be "breathing" cyan (light blue).
Once your Photon has downloaded the new app and restarted, your new app will automatically start running:
Confirm that the blue D7 LED light on your Photon's circuit board blinks on and off in a repeating pattern (with the light turning on for 1 second and then turning off for 1 second).
If so, then you've successfully programmed the "Hello World" app for your Photon device. Your teacher may want to see your Photon device to confirm that your team's app is working.
APP ISSUES: If the app doesn't work correctly (such as: D7 LED doesn't turn on, D7 LED doesn't turn off, etc.), then double-check your app code in Particle Build. If necessary, consult with another team or your teacher to figure out what the issue might be.
Your last step is to modify the "Hello World" app, as some extra practice.
In Particle Build, modify the code within the loop() function to change the LED blinking pattern. Here are some possible options your team could choose:
Make the D7 LED blink faster
Make the D7 LED blink slower
Make the D7 LED blink in a different pattern (such as two quick blinks followed by a longer pause)
It's recommended to add a comment at the very beginning of your code to list a title for your app, plus any other information that might be helpful to you or to anyone else reviewing the program code.
For example, this comment could list your app's title, your team's information (team name and/or team members), your teacher's name, and your class period.
Add a block comment at the beginning of your app code before the setup() function:
Modify this comment to list your specific information. Check with your teacher to find out if there is other information that should be listed within this block comment.
Flash your modified app to your Photon to confirm it does what you intended it to do.
Your teacher may want to see your modified app code running on your Photon.
If you need to download a copy of your app code to your computer in order to submit it to your teacher, there are two different download icons shown in the Code Menu panel:
The first icon (cloud with download arrow) to the right of "Current App" is used to download the compiled version of the app (firmware binary).
The second icon (angle brackets with download arrow) to the right of "Files" is used to download a zip file containing your app source code (.ino file).
Click the second download icon to download a zip file containing your app source code:
In this case, the zip file will be named hello-world.zip. You'll need to uncompress the zip file to get your app source code file, which will be named hello-word.ino. If necessary, this .ino file can be opened in a text editor on your computer.
UNCOMPRESS ZIP: To uncompress a zip file downloaded to your computer:
On a Windows computer, right-click the zip file, and select "Extract All." Browse to the destination folder where you want to save the uncompressed file, and click "Extract."
On a Mac computer, just double-click the zip file.
In the next tutorial, you'll start connect an input and output to your Photon to create a "Smart Light" device.
Next you'll add commands in your app code to turn the LED on and off in a repeating pattern.
Your app can receive signals from inputs using the digitalRead() or analogRead() methods, depending on whether the values being received will be digital or analog.
Your app can send signals to outputs using the digitalWrite() or analogWrite() methods, depending on whether the values being sent will be digital or analog.
DIGITAL VS. ANALOG: Digital inputs and outputs use binary values (such as: HIGH vs. LOW, etc.). Analog inputs and outputs use a range of values (such as: 0-255, etc.)
The LED can be controlled as a digital output that is either "on" or "off".
You'll need to send an "on" signal to the LED pin. Add this code to your app by inserting it within the loop() function (between the curly braces):
The digitalWrite() method requires two parameters inside its parentheses (in this order):
The I/O pin number, which can be the actual pin number (such as: D7, etc.) or a variable that stores a pin number. In this case, the variable LED is listed (which has a value equal to D7).
The signal value, which can be HIGH or LOW. Your Photon uses this value to send an electrical signal through the pin: HIGH is a signal of 3.3 volts which represents "on," while LOW is a signal of 0 volts which represents "off." In this case, the signal was set to HIGH because you want to turn on the LED light.
You'll want to leave the LED turned on for a short amount of time before you send the "off" signal.
Because the Photon's app code runs very fast, there will be certain situations where you'll want to insert delays into the code, in order to allow time for certain events to occur. Typically, these delays are intended to give people time to perceive the event and/or respond to the event.
Your app can use the delay() method to insert a time delay. It acts like a timer that makes the app wait before performing the next line of code.
You'll need to add a delay after the LED has been turned on. Add this code to your app by inserting it (as a separate line of code) within the loop() function (after the digitalWrite() statement):
The delay() method requires one parameter inside its parentheses:
The time value, which can be an integer number (whole number) or a variable that stores an integer. The value represents the number of milliseconds for the delay (1000 ms = 1 second). In this case, the delay was set to 1000 ms (1 second).
Next, you'll send an "off" signal to the LED pin. Add this code to your app by inserting it (as a separate line of code) within the loop() function (after the delay() statement):
You can see that the second parameter in this digitalWrite() statement was set to LOW, which represents "off" for a digital output.
When all the code within the loop() function has been performed, the loop() will automatically repeat itself. Since the first line of code in your loop() turns on the LED, you'll want to add another delay to leave the LED turned off for a short amount of time before the loop() repeats itself.
Add this code to your app by inserting it within the loop() function (after the second digitalWrite() statement):
Now, the code within your loop() function should perform these tasks (in order):
Turn On LED light
Wait 1 second
Turn Off LED light
Wait 1 second
Repeat
REPEATING LOOP: You don't need to add a command to make the loop() function repeat – it automatically repeats itself after its last line of code has been performed.
SETUP NEW DEVICE: The Photon device provided to you by your teacher should already be setup with a Wi-Fi login and Particle account that you will use. If not, then the Photon will need to be by programming it with a Wi-Fi login, creating a Particle account, and adding the device to your account by claiming its device ID.
VOID: Why is 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.
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 or .
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 statement for the library at the beginning of your app code.
WIRING VS. ARDUINO: is another programming language framework for microcontrollers. It turns out that Arduino is based on Wiring, so the two languages are nearly identical (though there are some differences). In most cases, a program originally written in Arduino will work on your Photon with only minor revisions. So once you've learned how to program in one of these languages, you've basically learned both.
Icon | Name | Purpose |
Flash | Flashes the current app to your Photon device over Wi-Fi (The app will first be saved and verified. If there are errors in the app, it will not be flashed.) |
Verify | Complies the current app to check for errors (The app will first be saved.) |
Save | Saves the current app in Particle Build |
Code | Lists all your saved apps. Click an app's title to open it in the code editor. |
Libraries | Lists libraries that can be included in your app to add functionality |
Help | Lists quick help for device (might not be available for your Photon) |
Docs | Opens new tab with Particle Reference Documentation for your device |
Devices | Lists your devices. You can view the device ID, and signal device over Wi-Fi. (If you have multiple devices, you can select which device to flash apps to.) |
Console | Opens new tab with Console showing your device's events in Particle Cloud |
Settings | Provides options to: log out, change password, or get your access token. |
Next you'll add a command in your app code to designate the LED pin as an output.
A variety of inputs and outputs can be connected to the I/O pins on your Photon circuit board. Your app code needs to identify which I/O pins are being used and whether each of these pins will be used for an input or output. This is referred to as setting the pin modes.
You'll need to set the pin mode for the built-in LED that you'll be using. Add this code to your app by inserting it within the setup() function (between the curly braces):
The pinMode() method requires two parameters inside its parentheses (in this order):
The I/O pin number, which can be the actual pin number (such as: D7, etc.) or a variable that stores a pin number. In this case, the variable LED is listed (which has a value equal to D7).
The mode value, which can be INPUT, INPUT_PULLUP, or OUTPUT. Your Photon uses this value to change the electrical behavior of the pin, so the pin can either receive signals from an input or send signals to an output. In this case, the mode was set to OUTPUT because your app will be sending "on" and "off" signals to the LED light.
At this point, your app code should look similar to this:
Notice that the pinMode() statement shown in the app code above is indented (using the tab key). This is a useful practice when adding code statements within curly braces because it helps make the code easier to read and understand – especially if your app contains many code statements nested within each other.
The Particle Build code editor does NOT check your code syntax as you type, so be sure to periodically verify your code to check for errors.
Verify your app code by clicking the Verify icon in the left navigation bar. (Particle Build will first save your code before verifying it.)
While Particle Build is verifying your code, it will display the message "Compiling code" in the status bar at the bottom of the code editor panel. When the verification process is complete, the status bar will indicate the results:
If your code compiled without any errors, the status bar will display a success message.
If your code contains an error, the status bar will display an error message with a description of the error and a link to the specific line number in your code where the error was detected (though sometimes the root cause of the error occurs on a previous line). You'll want to fix the error and then try verifying your code again.
MULTIPLE ERRORS: Sometimes your app code might contain multiple errors. However, Particle Build will stop verifying the code at the first error that is detected. Once you fix that error and verify the code again, you might see a new error message for another error that occurs later in the code.
