Arduino IoT is fabulously good, and needs to become much, much better

Just started with a MKR 1010 WIFI, and using it with IoT beta. In a few hours I got an object working, which is good, but nowhere good enough.

What’s missing? Documentation.

Start with the 1010:

  1. where is a data sheet worth its name?
  2. what are diodes? The green one? The blinking orange one?
  3. how do you use the diodes right next to the WIFI module? (the RGB diod).
  4. with the IoT can you make over the air changes to programs running on the 1010?
  5. the serial monitor works in a very strange manner with the desktop application - the serial monitor speed seems to adjust to what speed the 1010 sends at, or possibly the other way around
  6. a list of the pins, and the functions they provide (with restrictions)

Providing something like this will increase the usage because the tools are more productive to use. My time costs far more than a single card in just one hour. Reliable documentation will increase professional usage, and projects will change from fun hobby projects, over too more semiprofessional and professional usage.

Once a ‘reliable’ product in the sense that the user can read what he needs to know, rather than experimenting and picking up bits and pieces here and there (which is extremely time consuming), then you will find engineering shops buying the boards as productive convenience items (rather then a few as a possible solution for something simple).

The same argument goes for IoT.
A documentation structure that looks like this:
Top level - General Information tells the user what it does, what the components are, etc
Usage level - Describe how you use it to solve a simple problem
Programming info - very program function

As an example, most prospective users don’t understand why they need IoT. The need is established through the General Information docs.

I’ll be happy to assist, but htis is not something I can do on my own (not knkowledgeable enough in Arduino, although I have put the boards to good use in serious applications like running pumps, alerting if there are problems, shutting them off if if they draw too much current, because the inlet is frozen, and if the fuse is blown, then it will not start once the temp is above zero, etc).

What do you think?

And any answers to the questions in the post are most welcome!

Peter Ljungqvist

plq:

  1. where is a data sheet worth its name?

For the Arduino boards, the closest thing you'll get to a datasheet is the documentation provided on the product page:
https://store.arduino.cc/usa/arduino-mkr-wifi-1010
There is some additional documentation, which is a bit less "datasheety" on the Getting Started page for each board:

Keep in mind that the MKR 1010 is just a PCB with a microcontroller, WiFi module, crypto chip, and the necessary support components. You will find documentation of this in the schematic and board design files provided on the product page. You can find a formal datasheet for each of those components on the manufacturer's website. It would not make sense for Arduino to attempt to duplicate all that information.

plq:
2. what are diodes? The green one? The blinking orange one?

The green LED with the silkscreen marking "ON" is the power indicator. It is on whenever the board is powered.

The orange LED with the silkscreen marking "CHRG" indicates the battery charging state.

There is also a yellow LED, which does not have a silkscreen marking. This LED is connected to the pin LED_BUILTIN and you can control it from your sketch. It can be useful as an indicator or a debug tool. That LED also serves as an indicator of the bootloader. When the bootloader is activated, it will pulse and during upload it will blink rapidly.

The LEDs are actually standardized across the MKR boards. For some reason, they are well documented in the MKR Zero product page but that information has not been copy pasted to all the other product pages. It gives a nice explanation of the CHRG LED:

The CHARGE LED on the board is driven by the charger chip that monitors the current drawn by the Li-Po battery while charging. Usually it will lit up when the board gets 5V from VIN or USB and the chip starts charging the Li-Po battery connected to the JST connector. There are several occasions where this LED will start to blink at a frequency of about 2Hz. This flashing is caused by the following conditions maintained for a long time (from 20 to 70 minutes): - No battery is connected to JST connector. - Overdischarged/damaged battery is connected. It can't be recharged. - A fully charged battery is put through another unnecessary charging cycle. This is done disconnecting and reconnecting either VIN or the battery itself while VIN is connected.

Hopefully Arduino will take the time to add this, and the similar important information to all the MKR board product pages soon.

plq:
3. how do you use the diodes right next to the WIFI module? (the RGB diod).

I'm not certain, but I think we might have an explanation of that on the Getting Started page for the Uno WiFi Rev2 (which also uses the NINA WiFi module):

Close to the Nina module and the ICSP connector there is a square RGB SMD LED. This LED is directly connected to the NINA-W13 WiFi module and it is driven by the module itself. It will be used for future applications and developments.

So it seems this LED is reserved for future use. Hopefully once that has been implemented it will be properly documented.

plq:
5. the serial monitor works in a very strange manner with the desktop application - the serial monitor speed seems to adjust to what speed the 1010 sends at, or possibly the other way around

This is the way all the USB CDC serial ports work. The baud rate you set in Serial.begin() makes no difference. It's only on the boards like Uno, Mega, Nano that connect to the computer over a true serial port on the microcontroller that the baud rate is set by the sketch.

plq:
6. a list of the pins, and the functions they provide (with restrictions)

This is done to some extent on the "Tech Specs" tab of the MKR WiFi 1010 product page. However, traditionally it is also done in a more verbose and complete manner on the "Documentation" tab of the product page and I would really like to see that done for the MKR WiFi 1010.

plq:
Reliable documentation will increase professional usage

Not only that, good documentation is so important to the non-professional beginner/learning users that Arduino is intended to be friendly towards. A professional may take the time to dig into the datasheets and schematics and source code to get the information they need but the average kid who just wants to make a cool robot but has social media, video games, movies, etc. competing for their attention is going to get frustrated, put the Arduino in a drawer, and forget about it.

plq:
I'll be happy to assist

Thanks! Suggestions for how the documentation can be improved or reports of errors in it are a very valuable contribution to the Arduino project. Someone looking at it with a fresh set of eyes and a different viewpoint can spot things that the documentation authors who are overly familiar with the subject matter already don't see.

The best way to get these suggestions to the people who can make the necessary changes is to open issue reports in the bug tracker here:

In addition to being the place to report bugs in the Arduino IDE, that tracker acts as the "catch-all" for topics which don't have their own dedicated Arduino repository, including product documentation. Before submitting an issue report there, please take a minute to do a search of the existing issues to make sure someone else hasn't already submitted a report for the same thing.

The more specific you can be about your suggestion, the better. I have found very good results when I provide the full and exact text that I want added or changed. Perhaps the person making the documentation change may improve on it a bit, but this gives then a very good starting point.

Thanks for the useful feedback! Documentation will surely come as soon as possible, we are working on it. For now, you can take a look at the new IoT Cloud tutorial we've just released on Project Hub --> IoT Cloud - Getting Started - Arduino Project Hub

A link to this project will be soon added to the Arduino IoT Cloud landing page.