Another New User Experience

Troubleshooting
1

Background. My brother purchased a Photon and handed it to me when I was visiting in a family situation to maybe help give the kids something interesting to do. So I had zero background on even deciding on the purchase. Bottom line, there are ZERO guides that don’t assume something that will throw a new user into “What the !@## are they talking about???” And I’ve been working with desktop PCs since “IBM compatible” was a selling point. Mostly Windows, as that is what the “average” user found. But also a little Linux.

I have a PhotonNH, but right away the instructions start taking about a “CORE.” OK, first I have to go learn what a CORE is. The device. Oh, OK. Why not just call it that?
So I get putty. But then have to go figure out why Win10 doesn’t list any ports. On your own . . . OK, run this code that looks like Linux, no explanation of what to expect to see.
Except putty stops echoing the keyboard. No real help found anywhere for that. So I just keep trying.

OK, I’ve managed to get the device ID. Make sure I have a flashing blue. Start the Photon app on my phone (Galaxy S6). "No Photon devices found."
Try my Nvida tablet: “No Photon devices found.” Check wifi in use, yes, tablet is 2.4 (learned that from this forum, something else not provided to a NOOB).

So now I have a another laundry of things to do to try and flash the device, ops, “CORE”, sold as a PhotonNH . . . but no explanation on what the commands I’m told to enter mean, or what result to expect. Still no idea what the “dfu-util” is, or, heaven forbid, be told what the !@#$ title means. “Once the Particle CLI and dfu-util are installed, you have to enter DFU mode.” Oh gee, now isn’t that clear? From inside the Particle CLI? or the dfu-util? Screen shot??? Jeeze I paste these into PowerPoint, or OpenOffice Impress, at least 3 times a week for co-workers who need just a little help. Too much for real programmers. Us poor mortals are simply on our own . . . but please, I have a masters degree, don’t give me some video to watch. Can I just have some instructions that assume a new user needs each step explained?

Times up. Been at it off and on as I could spare time all week, kids got zero out of it, I still can’t connect to the device/CORE/PhotonNH, and am now out of time. Leaving tomorrow to return to Virginia from Idaho. The device/CORE/PhotonHN is going back in its cute little can and will probably still be sitting there when I return next year. I will probably drag along my Ubuntu netbook just to have a different set of instructions to try and follow. Unless my brother has thrown it either up against the wall or into the trash. He is a College CNC instructor, but I have a suspicion he won’t be half as patient as I’ve been . . . or maybe I just need to go buy this Oreilly book that’s popped up as a "Your topic is similar to. . . " window.

No need to answer as I won’t have the device/CORE/PhotonNH to try any more troubleshooting. But maybe this will help someone else so they won’t feel stupid.

2

Happy to provide help in setting things up if you are getting back to tinkering next time. :wink:

1 Like
3

Sorry to hear you've had a bad experience, that's certainly not the way it's supposed to be.
I'd like to address some of the points you've raised:

If you're new to the docs, you should land on this page:

image.png1022×654 123 KB

If you don't get that, there's always the switcher on the top which allows you to select your device:

Where did it mention that you needed Putty? Either the App or the CLI (using the installer) should work fine.[quote="KellisRJ, post:1, topic:32963"]
OK, I've managed to get the device ID.
[/quote]

Not sure what you need that for either (at this point).

I'll assume the device was in listening mode?

The CLI is documented, and so is DFU mode.

The docs are open source, and any contributions are always highly welcome. If you could point out some of the sore spots (with links), that'd help too!

3 Likes
4

Obviously I mixed up where I got what in my bouncing around trying to figure out how to get connected. Since receiving your reply, None of those images show the product I have nor did the single document in the package point to the correct page. I bounced around your site a little more as “Photon” on the page/images you show isn’t the PhotonNH but I figure you have some points, so even without a good link, I’ll poke around. Under the Hardware header you have the “Internet Button is a ready-to-use IoT device” . . . FYI, one of the things beat into my head as a young writer was to always spell out an initialism the first time it is used “Internet of Things.” Why make a customer go look for something? Like I said, I didn’t pick it out, and I suspect I’m not the only one who will get one that way. The package said I had a “Protron” so it seems pretty reasonable to start with the “PHOTON (WI-FI)” link not knowing that what I have is a “Internet Button.” And why would I go looking for something else?

“INTERNET BUTTON - LIBRARY” is ~ 1/3 down the page. Why assume I’m going to read past all the things that don’t apply to me? How much time do you like to spend reading ill-revilement technical information? My item had no separate LED, jumpers, etc. How about simply put a few hyperlinks at the top of the page to the relevant section? Or from the “Hardware” page? I think I was the time I read about miss-printed boards I went off on a tangent looking at the board and trying to figure out the markings and then thinking I needed to know this because I was going to have to attach something . . . regardless, I couldn’t get a connection, so went looking to see if there was anyway to connect through the cable. And that lead me to putty, where upon I started to mix up what I had gotten where.

So I see your points, do you see mine?

Ron

5

I'm more than a bit confused, but let's see.

I had no idea whatsoever which product you do have at this point, but does it at least vague resemble one of the four for the image I posted? (I feel like it's the Photon, but that's just a hunch).[quote="KellisRJ, post:4, topic:32963"]
I bounced around your site a little more as "Photon" on the page/images you show isn't the PhotonNH
[/quote]

That certainly still is a Photon, it just has No Headers. Cutting off your fingers doesn't make you any less human ;).[quote="KellisRJ, post:4, topic:32963"]
Under the Hardware header you have the "Internet Button is a ready-to-use IoT device" . . . FYI, one of the things beat into my head as a young writer was to always spell out an initialism the first time it is used "Internet of Things." Why make a customer go look for something?
[/quote]

Like the first paragraph on the home page?
[quote="KellisRJ, post:4, topic:32963"]
The package said I had a "Protron" so it seems pretty reasonable to start with the "PHOTON (WI-FI)" link not knowing that what I have is a "Internet Button." And why would I go looking for something else?
[/quote]

Particle doesn't have a 'Proton', so that's on whoever wrote that on said box. That Internet Button you have is still using a Photon though. The 'button' is merely a shield you can plug it into. It wouldn't be bad it it had the name on it though, fair enough.

A link would be great here, since I've got no idea what 'page' you're talking about. I'll assume it's the docs over here.
If that's the case, then it makes sense that the internet button is halfway down the page, since there's no reason to put it any higher. Particle offers multiple products, and there's no incentive to prioritize the Internet Button over any of the other products.

Again, there are more products out there than the one you've got, and those have to be documented too. There's a sidebar menu that should make it easier to navigate to the one you need though.

Seeing as the package you took it out from had the wrong name on it, those items might have been lost while placing it in there? If it's indeed the Internet button, then yes, it doesn't have separate parts as such. If you could show me a link where it does, that'd be great.
There's a huge link with "see our Internet button documentation" on the hardware page of the internet button though.

I sincerely doubt the board was printed incorrectly, but I'd love to be proven wrong. If you can get a hold of a picture of the board, that'd be great.

I'm trying, but the lack of links/context makes it hard to guess what you're talking about at points. Any and all additional information you could provide would be greatly appreciated!

2 Likes
6

Guess what? You win. Enjoy your victory. I get the impression that’s much more important to you than providing any assistance or looking at things from my viewpoint.

Ron

7

Hi @KellisRJ,

As a third party observer of this thread, I can understand the frustration buried beneath the posts on both sides.

On one side, I understand from your point of view how difficult it can be to pick up and learn a new platform. There is jargon and paradigms which are unique to this platform, and until you become familiar with it, it is very easy to get off track while reading the documentation and wasting time trying to just find your bearings. This would be true of any new platform you try to become familiar with.

On the other hand, it is difficult as an Elite to try to answer questions and help people when they don’t provide the information you need or misunderstand or don’t read the right parts of the documentation, and sometimes there can be a tendency to point out these failings.

But to @KellisRJ I would say, I have used MCUs from many companies, and the Elites and people from Particle are unequalled in their dedication to provide sincere support on this forum. They are really trying to make their documentation the best and can be, and I cannot believe the amount of time they devote to answering questions here, from the most basic beginner questions to the most sophisticated. Honestly, if you want to enter into the fun world of Microcomputers, there is no better place to go. But there is a learning curve, and if you aren’t willing to climb that curve I don’t see how you will succeed with any Microcomputer.

3 Likes
8

You made a lot of great points...

From being a constant observer here, your experience isn't unique. Frankly, not being born into the world of micro-controllers (yet working with people on my team who are) we continue to suffer through the documentation as well. It is fragmented, and compartmentalized in a way that is difficult to navigate. Changes occur often and there are few pointers on the website that provide links back to the source code if you need to get there...

While it is nice that there are folks to defend what's here, only the most arrogant of companies/people would deny that there are areas to make improvements in the Particle space.

All that said, the community here, along with some key Particle folks can frequently assist, and that community manages to fill most of the holes.

I think if you are willing to take another whack at it (and with even more patience :sweat: ) you will get the help you need to get where you want to go if not as quickly as you may have expected.

3 Likes
9

Happy to provide more help whenever you need.

Just @kennethlimcp and i’ll be there :wink:

2 Likes
10

I'm not here to 'fight' over the documentation, nor am I here to 'win' anything. The only 'win' that could come out of here would be an improvement of the docs, since that'd benefit everyone. Unfortunately, that cannot be done until it's clear what exactly we're talking about and/or looking at. Many of the things you've mentioned are documented in some way, shape or form, which is what I've been trying to point out. Yes, the docs are rather large, but it has to match the product offerings, and thus can't be 'personalised' to the specific product you're handling at the time.

That's the biggest hurdle to understanding all the issues mentioned. I'm still a bit unclear about which device we're talking about and which exact pages/parts of the docs were mentioned. It's difficult to improve them if we don't know what to look for. Having been familiar with the platform for a couple of years, we tend to not notice things beginners might struggle with, which is why it's important that it's pointed out as accurately as possible. Better yet, if you can provide improvements, or suggest them, by making a Github issue/pull request on the specific page, that'd be even better.

Agreed. There's certainly a curve to it, but it's worthwhile climbing. In fact, the Spark Core was my first microcontroller, so I can attest to the fact that it's doable, given that you're willing to put in some effort.

Just to be clear, I'll be the very last person to say that the docs are flawless. I will, however, say that the docs are pretty good (if compared to other platforms). I've got plenty of ideas for improvement, but resources/time are limited, and there's only so much we can do. To prioritize efforts, we need some specific data on what exactly to look at, rather than going over everything and guessing.

2 Likes
11

My nephews have a "https://www.particle.io/products/hardware/internet-button"
The small oval paper in the can gave https://particle.io as the place to go for more information.

Not having anything in front of me now, IIRC, I learned from the packing slip I had a Photon, and maybe(?) it was the board that said Photon NH?? So started on this link:[https://www.particle.io/products/hardware/photon-wifi-dev-kit] Much, much later I realized I had a https://www.particle.io/products/hardware/internet-button but nothing in the package told me that, nor, given the same information I had available, did anyone else here realize I had a Internet Button. Nor is it shown in the group of products shown in the earlier response.

So none of us were able to use the information I had available to figure out the product. No wonder I was confused, and it seems those who know the products best were just as confused. I’ve looked for the reference I had open yesterday on the mis-marked board, and can’t find it again. When I have time, I’ll try to find it again.

Reading down the [https://www.particle.io/products/hardware/photon-wifi-dev-kit] page I got to: See our documentation for more details with this link: https://docs.particle.io/datasheets/photon-datasheet/

Still had no idea that I had an Internet Button with the “Photon” built into it . . .

And from there, because I couldn’t figure out how to connect to the thing after going through many more pages than I can remember, or even guess at what order I hit them in, I wandered all over, ended up using a web search and landed here:https://www.instructables.com/id/Getting-a-Spark-Core-running-without-using-Sparks-/ that got me started on the Spark and device, and putty etc . . . in part because I was desperately trying to avoid a delayed question/answer that would extend beyond the limited time in ID that I had available . . .

For what it’s worth. I’ve taught over 100 students basic bicycle maintenance over the past five years as a bicycle coop volunteer. Including a class last night. Often to people who are confused right from the beginning by “Righty tighty, lefty loosly.” I go over that all almost of the terms will be new, may not mean what they thought they mean, and I expect you all to say “Wait, what part are you talking about again?” And variations on 1,000 other things . . .
“Wheel” =

  • Rim
    – clincher type
    – Glue-on type. You will probably never see, but ya never really know . . .
  • Tire
    – sidewall
    – cap
    – steel bead that won’t stretch
  • Inner tube (get the correct type for a spare)
    • A Schreader inner tube has a thick valve stem like a German beer stein and has a spring to close them
    • A Presta inner tube has a thin valve stem like a French wine glass stem and rely on air pressure to close them.

So I have a basic understanding of making sure we are all talking about the same thing.

Last night it took almost 90 minutes to teach four students how to release their brakes (Oh, they open up??), open the (almost 90% of the time over tightened) skewers, show what a cam-lock is, explain why too tight is as bad as too loose {anyone here know why?}, loosen them enough to get past the wheel retention device so the wheel can be removed, remove the wheel, reinstall it, show how to properly set the pressure on the cam-lock, reattach the brakes, and what’s different on the rear wheel. Derailleur, the difference between the one student with a single speed, and the other with an internally geared hub with anti-rotation washers and a shifter cable to disconnect. And oh, sorry, you have one of the miserable, poorly, IMHO, designed derailleur hangers that make reinstalling the, "Gee it wasn’t hard to get off . . . " wheel back on. And oh, the metal moves, so you may have to open the skewer up more to reinstall it, or, if the chain stays move inward, may have to leaver the wheel back into the drop outs. Oh this is the drop-out. You have a horizontal, and here is why you can’t just pull the axle all the way back on both sides . . .

So I have bi-weekly experience in helping others who may have never picked up anything other than an open-end adjustable wrench in the steep learning curve of something they are completely unfamiliar with. Society of Automotive Engineers (SAE) Imperial/fractional or metric fasteners?

But I had nothing in the package, or on the pages I checked for a Proton, to let me know I had an Internet Button. So I didn’t even know I had a bike, let alone that this one had an internally geared hub and not a derailleur. Perhaps “if” on the page with the four photos there had been a 5th photo with the Internet Button, things would have gone a bit simpler. But it didn’t, so I proceeded in profound ignorance doing the best I could with what I had.

Next time I’m at my nephews, I’ll follow the instructions on the “Internet Button” page, under the “Hardware” heading and report back on how it goes. And I’ll give my brother a heads up on what he has.

A Photon is an Internet of Things “Internet Button.” https://www.particle.io/products/hardware/internet-button
From the Hardware hyperlink you get:
Hardware Solutions
INTERNET BUTTON
Press a button to trigger something on the internet, with lights and sound.
From there you get:
“The Internet Button
The Internet Button is a ready-to-use IoT device with sensors, LEDs, and more. Place orders online, send emails, receive notifications, track feedback, and develop hundreds of other applications.”

And I’ll give him the heads up on what a IoT is . . .

“Ja ne, gomen kudasai.” Best wishes everyone, a repeat lesson in making sure we understand what is the “real problem?” Or are we really even speaking the same language . . .

Ron

12

Just for the records, an InternetButton comes like this

image.jpg1177×1051 263 KB

image.jpg1599×1361 431 KB

image.jpg1673×762 267 KB

Not a lot more for Particle to do about informing you what product you're dealing with.

And as you said in your OP

there was no reason for us to doubt your statement as there is a Photon (even a Photon with No Headers) and that would be one of the four devices pictured and mentioned in docs - so why would we need to assume you weren't meaning them. But if we asked members such questions like: "Are you sure it's a Photon?", we also get snappy replies, so we are at a loss whatever we do (for Elites that is absolutely voluntary and free of charge, just because we want to give things back to Particle and the community).

BTW, when you teach others about bikes, are you doing that in person or without the short-cycle feedback loop and without seeing anything but written text (which could have been helped by attaching a pic of your device)? We are doing all of this the latter way. Try doing your courses that way.
If you had a "student" asking you via mail how to adjust his "Shimano BR-785 Hydraulic Disc Break", would your first question be: "Are you sure you aren't talking about a Specialized Diverge Comp M CEN?"
Sorry, but I'd assume you'd just take the rather specific statement for what it is - at least at first.

And about language, for @moors7 or myself our first language isn't English either :wink: But we try our best.

13

The Internet Button isn’t shown in the pictures I was first provided nor anyplace I looked on the site, a later point I made. Perhaps it ‘should’ be?

Sorry, but it never occurred to me to look under the can when I had what I “assumed” to be the proper guidance on the enclosed document. Why would I?

"Leaving tomorrow to return to Virginia from Idaho. . . . No need to answer as I won’t have the device/CORE/PhotonNH to try any more troubleshooting. " So I said I no longer had the item in front of me very early on.

“Gosh Ron, a lot of what you are saying doesn’t make sense, I’m not sure how to help you. Let’s start by making sure we are talking about the same thing. I read you no longer have access to the item, but maybe we can set you up for when you do, or maybe you will decide to purchase another to practice on. Here are links to pictures of all of our products. When you have a chance, please let me know what you have so we can try to set you up to succeed. Oh, and “NH” means Non Header, and mentioning that has confused me even more. So to help, I’m going to have to ask you to help me figure out what item you have,”

I realize not much I say will add to this, “but” I’ve also been assisting others repair their vintage sewing machines via Yahoo! board postings for well over a decade. Often starting with “the stabber thingy isn’t moving . . .” so yes, I do have some idea of how to translate non-technical terms, teaching as I go. Or point others to resources that may help us be sure we are talking about the same thing. I don’t speak any Spanish, but at the coop have helped a fair number of people get what they need done, whether they understand that as a coop I’m “supposed” to be helping them learn the task, not do it for them.

So you are justified, I’m not. Obviously no one else has had the problems I had, so I must be an outlier in the 4th quartile of folks who need to leave these things to other, smarter people who will think to look on the bottom of the package for instructions, even if they no longer have the item to look at . . .

Best wishes,

16

@will, handling this over to you.

2 Likes
17

@KellisRJ I appreciate your feedback. Our documentation is certainly not perfect, and the Elite are among those who are quickest to point out the shortcomings of our onboarding instructions. Particle is a small team trying to provide a smooth user experience built on an extremely broad hardware and software stack, but our goal is absolutely to provide a better and easier development experience than you should expect from any other MCU platform, so you’re experiences are absolutely valid.

It sounds like this process may have exhausted your patience, but in the case that it hasn’t, I’d be happy to extend a discount code on a future purchase (via PM) so you can properly experience our “out-of-box” onboarding flow and provide in-context feedback and opportunities to improve. Even if you wait a year to reevaluate Particle, I hope you give the platform another try, since we’re constantly making improvements to the onboarding experience.

That all being said, Particle’s development community is different from others on the Internet. Despite the seemingly endless frustration supplied by embedded systems engineering troubleshooting, we will not play host to rude or inflammatory language. Everyone on this forum is a human being that deserves respect, so please do not allow your frustration with a company or a product influence the way you communicate with others on this site. We are all a part of the same community.

Thank you again for sharing your frustration. Please feel free to @ me in the future if you have more actionable feedback that we can incorporate into the product.

7 Likes