Teaching the Introduction to the Internet of Things lesson

In a post-workshop survey, a learner responded to the question “Please provide an example of how an instructor or helper affected your learning experience” with this comment:

I had a question that I was shy about, when they were faced with a similar issue they smiled and said, “we don’t know the answer as well, let’s search for it”. It was really enjoyable to be around them.

To me, as a Carpentries Instructor, this is not just the epitome of a complement, but also captures the essence of our workshops.

The Introduction to the Internet of Things (IoT) lesson is still in The Carpentries Incubator, and this was the second time I had the opportunity to present it. The content of this lesson, in particular, offers some significant challenges. In my Introduction to the workshop, I told the learners to expect things not to go smoothly. However, all the things that were going to go wrong were to serve as part of the learning experience. I am sure many will nod their heads in agreement if I say that the worst thing you can do during a presentation is to try and deliver a live demonstration - of any sort - because if you create an opportunity for chaos to creep in, it will. In a workshop such as this one, the laws of chaos govern.

In case I am exaggerating, or if you think I am silly for having been particularly nervous about this workshop, I’ll share my experience of a few weeks ago when I decided to run an IoT taster session during our Code Community meetup. The meetup was also supposed to serve as a test run for the one-day workshop.

Code Community was scheduled for 12:00 to 2:00 p.m., so I had the morning to ensure everything was still working. I created a RaspAP access point and an MQTT server from a Raspberry Pi 4 (RPi) with 2GB RAM. All I had to do was switch the RPi on. I tested it, and it was working well. I could connect my laptop to RaspAP, and I could also upload code from the Arduino IDE on my laptop to an ESP32 and connected to the RPi. The ESP32 would, in return, publish some information to the MQTT server. From my laptop, using MQTTx, I could subscribe to the published topic.

An ESP32 Wroom 32 microcontroller

At 11:30 a.m., all was shut down and packed up in my very fancy waterproof case with wheels and a retractable handle. A colleague gave me a hand with all that needed lugging to the other side of our campus where our venue for Code Community was. I even remembered my multi-plug extension towers - three giving 24 sockets. Each of the 12 people that signed up could plug their laptops in twice.

No worries, I thought; I brought my other laptop. But, alas, the workstation connected to the large screens in front of the room was missing an HDMI cable, so I could not plug it in. I could not use the workstation connected to the screens because it was connected to the network with an Ethernet cable and did not have WiFi. I thought I could talk people through the process, so I asked them to connect to the RaspAP and gave them the SSID and password. But, alas, they could not connect again, so the apparent problem had to be the password, but I checked and had it right.

I pre-programmed the ESPs to connect to the RaspAP and then to publish “hello” to the MQTT server. At the same time, I was struggling with laptops; one of the guys, Ben, who had some experience with microcontrollers, managed to connect the ESP to his computer and noticed that the ESP did connect to both the RaspAP and MQTT server. Suspecting that the password I gave them was still incorrect, he dumped the code from the ESP to the computer and was able to spot the SSID and password. The password I gave them was correct, but none of the laptops would connect despite this confirmation. Ben then copied and pasted the password from the dumped code to his laptop, and to our amazement, the laptop connected. He even emailed the copied password to someone else, and at that point and they, too, could connect. If you pasted the copied password, the computer would connect, but if you typed it, it would not.

By now, people were helping one another and a few managed to upload code to the ESP and connect some sensors and LEDs to the ESPs. I talked a bit about the pre-loaded code and how the OTA code was meant to allow people to upload new code to the ESPs over the air without physical access to the controllers. I also explained a bit about what MQTT was and how it could be used. At least the meetup was a good use of time. People’s interest was captured, and a few showed an interest in attending the IoT workshop, which would be a few weeks later. The password mystery is still a mystery. After some contemplation and discussion, we decided the probable cause was a hyphen in the password encoded differently. Despite confirming this not to be the case in the dumped code, it still seemed the most feasible explanation.

Back to the main workshop. Everything that went wrong before worked perfectly well this time—an HDMI cable on the workstation connected to the big screens in front of the room. Only one person did not bring a laptop and could share it with another student. Only a couple of people did not install the required software, so the helpers sorted them out quickly. I made sure there was no hyphen in the password anymore, and all the computers could connect to the access point. More than enough other things could go wrong - and they did.

Here follows a list of those things and what we did to fix them:

1. Since I created the lesson less than a year ago, the Arduino IDE interface has changed quite a bit, so the software screenshots in the lesson did not reflect what the students were seeing. Thanks to the HDMI cable connected to the big screens, we could project our laptop installations so students could follow.

2. People using Linux may need to install the pyserial Python module to flash code to the ESP32. This is not well documented, as indicated by the fact that there are quite a few posts addressing this when you start googling the problem. The esp32 Board Manager includes esptool.py to handle flashing from the Arduino IDE. Esptool is run using the system Python installation. Some users who already work with Python (e.g. Conda users) may have a virtual environment set up by default in their $PATH, which you only discover when the student installs the pyserial module, which goes into their virtual environment, not system python, and the error persists. You can diagnose this using which python from a shell. Assuming that the Arduino IDE would be using the system python installation, we then suggested installing the module with sudo python3 -m pip install pyserial, which solved the problem. Modifying system python is probably not the ideal solution, but it was the quickest.

3. Unlike Macs and Linux PCs, Windows PCs must install the CP210x USB to UART Bridge VCP Drivers if one uses the ESP32 microcontroller boards. The instructions for doing it are in the notes, but if you accidentally skip that paragraph or get asked by a student why, unlike their neighbour, they cannot see the serial port before you get to that part in the lesson - do not forget that that might be the problem.

4. At our university, all the sockets in PC clusters are taken up by the PCs in the cluster. An odd socket might be located at least three to five meters away from the nearest desk. In meeting rooms, there are usually no sockets on the floor and probably one or two sockets in the wall at the opposite ends, also at least two meters away from the nearest seat. So, remember to take several strip plugs. I bought three multi-plug towers, which can take eight plugs each. But, depending on the room layout, eight people cannot reach the tower because of the tower’s cord length and the lengths of the laptop cords. There are, thus, three more towers on order.

Note: It is also nice if the towers, or strip plugs, have USB ports. You can then have students plug the microcontrollers into the USB port after it was programmed from the laptops to prove that, after programming, the microcontroller can run on its own without being connected to a computer.

1. Then there was also the issue that, in the new Arduino IDE which implements intellisense, the intellisense will not work under certain circumstances. When the IDE references a directory path with non-English (such as Arabic) characters, it cannot find that path. Although the intellisense will not work, it does not affect the compiler. Code will still compile.

2. If the default path used by the Arduino IDE for libraries contains non-English characters, the IDE won’t find the libraries. To fix the problem, the Sketchbook location can be changed in the preferences (i.e. Files, Preferences, Settings).

With a workshop such as this one, you have to realise that things will go wrong, even more so than regular workshops, and you can only prepare for some of it. This, for someone like me, is a hard pill to swallow. I’m the kind of person that walks around with a backpack that, besides the usual laptop, tablet and phone, also contains a Swiss Army pocketknife (that big one with a saw and scissors and all kinds of stuff that you might need), and a pocket-size titanium cutlery set which includes a straw and chopsticks. There is also a fingertip microscope, several versions of USB cables and at least one USB power bank. I wear a paracord bracelet because you never know when you will need 9 feet of rope to save the day. For some reason, though, I am always out of paracetamol…

However, by unapologetically warning folks that things will go wrong, I managed to convince myself that I have justified our unpreparedness for any unforeseen challenges that the universe may throw our way, and I enjoyed the workshop. However, I have to acknowledge my co-instructor, Samantha Finnigan, who knows much more about IoT than me. She is also younger, with better memory and goggles faster than me. With little planning or pre-workshop discussions, we worked together really well. I would present the lesson, and Samantha would drive the Arduino IDE displayed on the big screen for the students to follow and vice versa. I also had two marvellous helpers, Yash Borikar and Stuart Lewis. Based on the workshop feedback, the four of us presented a successful and enjoyable workshop.

Sometimes, we do receive seemingly contradictory feedback, like the following two comments about ways the workshop could be improved:

• More detailed explanation of the code used in this workshop would be nice.
• Considering that this is an IoT workshop and not a programming workshop, less time could have been spent on the programming and instead, focus more on practical examples of IoT.

Could we get it exactly right? Perhaps we can remember to ask for the patience of those more proficient learners in the workshop introduction. There are always a mix of people with different abilities at these workshops. Some will appreciate deeper explanations of things that others may find trivial.

If you are interested in presenting or contributing to the lesson, please find it in the Carpentries Incubator at https://github.com/carpentries-incubator/iot-novice.