[Howto] Setup photon if docs step fail

Since the Getting started docs for Photon does not mention anything about failed setup using the mobile apps, here’s a guide for users experiencing out-of-the-box issue.


The best tool is to use particle-cli and here’s some tutorial to install on your machine:

Once that is installed, ensure that the Photon is blinking blue [listening mode] and enter particle serial identify. This gives you a device id that we will use to claim the device to your account later.

Use particle login to logon or create a new account. Next, enter particle serial wifi and enter the wifi credentials of your network accordingly. The Photon will reboot and attempt to connect to the wifi and eventually be breathing cyan.

Once that is happening, enter particle device add xxxxxxx where xxxxxx is the device id obtained earlier.

If you have issues install particle-cli

  • Use a serial terminal program. If you have the Arduino IDE, that’s the serial monitor. Otherwise, coolterm for Mac and putty for Windows work great.
  • Check that the Photon is blinking blue [listening mode] and connect via Serial with 9600 Baudrate, 8 Databits, no Parity, 1 Stop bit
  • hit i on your keyboard to retrieve the device id
  • hit W on your keyboard and follow the steps to enter your wifi network credentials
  • the Photon should reboot and eventually enter breathing cyan state
  • Go to https://build.particle.io and login with your account
  • Hit the device tab and paste the device id to claim it.

07 July 2015


Please tell us newbies what is SUPPOSED to happen - we are new, we don’t know what “working” even means yet.
For example - my new photon goes through a range of colours, then does the “breathing” thing for a minute or so, then rapid cyan flashing, then magenta dlashing, then cyan flashing again, and every minute or so changes back and forth between all those things. I’m guessing this is bad, but I have no idea, because you have not told us.

Also - you idea of a “tutorial” for that particle-cli stuff - no - it’s not a tutorial: it’s a bunch of incomprehensible URLs and assorted gibberish without any actual instructions or explanations. I’m deeply disjointed about the new-user experience. Please find some folks, give them a photon, then stand behind, say nothing, and watch as everything falls apart, and take notes about how to fix it all.

Yes, I get that you’re busy and lazy (and say as such), but when even a seasoned expert coder like myself has no idea how to set this stuff up - I’m guessing you’re destroying every advocate and most of your potential market the instant they open your box.

Do consider writing a better tutorial :slight_smile: I spend my free time as a non-employed person writing to help people so those comments sounds disheartening. If it didn’t helped you, you can look for official support at support@particle.io

@harrisonhjones and @kmmonk gonna leave it to you guys to handle this :cry:


Thanks! I tried to type this out this morning, you were more eloquent! This woulda helped last night >.<

@cnd I think the flashing when getting connected for the first time is the photon updating it’s system firmware and there is 3 parts to it… so 3 lots of flashes… be patient and eventually it will finish and you can start tinker-ing


@Hootie 81 - thanks! I left it for hours, and it kept uploading a status about updating, over and over, and resetting, in an endless loop. Eventually, I reset it and tried the “reflash tinker” thing, and connected it to a different wifi network, after which it did the breathing-magenta thing for an hour (yes, the one colour combo they didn’t document. grrr), but eventually it seemed to calm down and start working (now that I know what working is!).

For any newbies like me: “working” means it’s “breathing cyan” (continuously, and only: not doing anything else at all, and not looping back into other colours either)… not to mention the bleeding obvious - it shows up as “online” in your app. (which is not obvious really: if you’ve never seen or played with one of these things before and it only ever says “offline” - it’s kinda hard to know if we’re supposed to do something to solve that ourselves…)

Hi, @cnd.

I can understand your confusion regarding your Photon’s first connection to WiFi-- it goes through a lot of colors and if you’ve never used one before (which is usually the case) it’s hard to divine what’s happening. To that end, we’ve included description of the colors that the Photon goes through on initial setup here under Step 3. If you have thoughts on where we can put that so that it’s more visible, I’d love to include it somewhere more obvious in the new docs we are putting together.

A Photon that is truly “online” should indeed be breathing cyan continuously, and it does get there after two minutes or so on that first WiFi connection. Your Photon does indeed seem to have a problem, which you have rightfully identified, since “breathing magenta” is not a thing we have programmed the Photons to do. If you PM me I’ll see what I can do about this one.

The support email is actually hello@particle.io, not support@particle.io, although I imagine that writing to support@ probably redirects. We’re quite overloaded with shipping questions there right now though, so PMing me will be the most efficient.

@christine - hi! Thanks for the personal reply. The 3 main problems I encountered were:

  1. Not knowing what it was supposed to do. I did find the colours without problem (the URL is written inside the box), but knowing what they are doesn’t help a new user who’s witnessing all kinds of “different”, but has no clue (yet) of what’s normal.

  2. The app mentions a “mode” button - which does not exist. It’s actually called “setup” on the board, as far as I can tell? (a better diagram on that /start page showing the components might be nice - with the setup button is clearly indicated, and maybe some mention of what it’s for?). I also wondered about that aerial pigtail socket - it also wasn’t clear if I was missing an antenna I needed to plug into that.

  3. breathing magenta: apparently this is something to do with firmware updates or some kind of boot load error. It happens, so obviously someone programmed it - there’s a bunch of other people in the forums talking about it - but none of them are relevant to what I was doing (I’m a 1st-time-user with nothing plugged in - they were seasoned dudes with wiring errors - said wiring causing that problem). If you didn’t program this in your main code - then I expect it’s coming from a boot block or whatever code runs before your code kicks in (or code that takes over when your code blows up maybe?)

*. note that I am your worst nightmare user though: it’s been a while since I ordered, and I’d forgotten what these were when they arrived. I’m also lazy and know too much for my own good.

My earlier suggestion does still stand though: find someone who has no idea what a “photon” is, sit them in front of a computer, put it in their hand, stand back, say nothing, and watch: you’ll observe all the traps they fall into that way :smile:

Wifi has 2 kinds of passwords: “text”, which everyone uses, or hex - which are 64 digits long, and almost nobody uses those. I do. Photon is happy to connect and uploads status data to your site fine, but seems not to update (it infinitely loops in the “comes online” and “update” messages). Maybe my extra long password broke something? To store it with a terminator would require 65 bytes at least - maybe that overflowed something?


You did the perfect thing, though! An abnormal behavior like this one is immediately recognizable because, well, it deviates from the docs. Writing in to this forum, poking the support page or emailing hello@ was definitely the right move at that point!

Yep. It was called MODE on the Core, some of the parts of the docs did not get updated when this changed. This will be fixed.

You’re sensing the right thing, which is that regardless of how it’s happening, it’s not normal behavior for right out of the box. You really shouldn’t have had this problem in the first place, I’m sorry you’re having to deal with it.

We’re working on docs right now to make it a little easier for people to get into the Photon. I’m really glad you wrote in here, because knowing the frustrations of folks like you really helps us develop. We can and will do new user studies, but I hope that everyone will keep letting us know on the community, through PM, and through hello@particle.io what they think we are doing wrong and right.

I’m going to leave it to @corey to answer this wifi password question.

1 Like

I too use the long hex password. I’m eager to hear what @corey has to say. Has s/he posted a reply anywhere??


1 Like


From what I’m reading, you’re using WEP long HEX password and you’re having issues?
If so, this is fix that is temporarily out of our hands (from what I’ve heard). We are currently working with Broadcom, very closely, on a deep firmware upgrade for this fix. I will post here when a solution is worked out between us.

Also, be aware that setting the Photon up on a 5GHz network is not viable/supported.
Last, check out our new awesome docs: https://docs.particle.io/guide/getting-started/start/photon/

-Corey :sunglasses:

Thanks for the prompt response, Corey! Sadly, it looks like I’m out of luck until there is a password fix.

I’m not using a 5Ghz network.

I followed your thorough instructions carefully. You may want to mention the use of particle serial wifi and what it means when certain error messages appear. (like Woops!)

Finally, I posted a detailed description of the things I did during setup of my Photon. Looks like the hex password issue is a show stopper, but it doesn’t explain (I don’t think) why the serial port created by Photon times out. Seems like that will have to be fixed before I can do any software update. I’m also guessing I’ll have to use DFU to do any update.


You’re right about the particle serial wifi part of being able to setup without Wifi, and then going to the online build ide to claim the device.

As for the DFU update, our firmware team put out an update yesterday/today, but it only updates the firmware binaries if the application firmware you are trying to use actually needs it.

I’ll keep posting to keep you updated!

Thanks for your response, @corey. As an update, I was able to try another network (WAP2 with a password) today. Worked fine. Breathing cyan just like it should and shows up on the dashboard when claimed.

So I eagerly await the WEP / hex password fix! Any expected date?


1 Like


Once we figure things out with Broadcom and some other people we’re working with on it.

I’m not sure on a definite date in place yet.


great work kennethlimcp!
Helped me a lot getting my photons up and running.

Particle team however: why are these procedures not mentioned anywhere in the docs? In particular in the getting started via USB section?
I know a few people who struggled just like me and kennethlimcp’s instructions in a prominent place in the docs would have saved us all some time…

@corey, is there a way to force the firmware update? We all know (well maybe not everyone, just those who have tried to use it) that the I2C is broken on the Photon. At this point I am desperate for working I2C as my projects depend on it. I have multiple Photons, Sparkfun Photon Weather Shields as well as numerous I2C breakout boards. None of these work more than a couple of data pulls before the data becomes corrupt.

A fix is currently being worked on and will be tested shortly. If that works, your best bet is to compile locally using that branch. You don’t really have to know how local compile works, as long as you can follow some relatively easy steps. It’s not a scary as it sounds.
That said, there currently isn’t yet an approves I2C fix, so forcing an update wouldn’t make much of a difference. Even if so, you’d probably have to compile your user firmware to the new version as well, for which you’d have to compile locally even if the you’d updated the system firmware. Unless the Cloud compiler is updated, updating your system firmware won’t make much of a difference in this regard I’m afraid.


Right, I have been hearing about a fix in the works for a month now. I first reported the issue to SparkFun and the author of the Guide for the SparkFun Photon Shield-it was a surprise to him as this worked at some point in development and then it became broken in a firmware release. It is unfortunate that it is taking so long while partners are selling Photon shields and breakout boards that basically don’t work. There is not a lot of visibility on the issue which is unfortunate. There were promises of a firmware update by Zach in his interview (eta last week). The more people that buy this hardware and run into problems the less likely they will support the Photon platform. The lack of more formal communication and expectation setting by Particle and SparkFun is really unacceptable. Continuing to advertise and sell broken hardware (e.g. SparkFun Photon Weather Shield), implying that it works is not good for customer relations.