Host Instructions
This instruction page is intended for host instructors
If you are a designated host instructor for IoT Workshop at Oracle Code event in a particular city, please contact Raymond Xie at yuhua.xie@oracle.com to get you some security credentials to access various components, including login to Raspberry Pi device, and login to the Oracle IoT Cloud Service (IoTCS) instance. By the time you try to set up at event site, you definitely should have the login information from Raymond already.
This page will cover two stations: 1. IoT Workshop session; 2. Pac-Man on a String game. They are two unrelated independent setup, and should be staffed by different people.
We have recorded some videos explaining the actual details of IoT Workshop session.
-
The equipment/system setup details before event starts (usually done one day ahead of actual event at a conference center). IoT Workshop setup
-
The actual details of how to conduct an IoT Workshop session. IoT Workshop session
-
The system setup details of Pac-Man on a String game, should be performed before the event starts. Pac-Man on a String game setup
-
Here is a video explaining how you play the Pac-Man on a String game, as well as how the game was built: Pac-Man on a String
Please watch the videos to get an idea of what your tasks are - both setting up system and facilitating the operation. Then you will be able to ask additional questions during the video conference call with Raymond before the events. Well prepared hosts usually have much smoother and productive sessions.
For the IoT Workshop station, we have a Netis Router, Raspberry Pi and a laptop showing IoTCS UI console. For the Pac-Man on a String game, we have a network switch, game box, LED Strip, tripod post, and a laptop showing Scoreboard and Leaderboard.
During each Oracle Code event, we will need one laptop for showing IoTCS console for IoTWorkshop session, and another laptop for displaying ScoreBoard for Pac-Man on a String game. The event venue may or may not provide laptops, so check with Oracle event setup coordinator. If event venue does not provide laptops, any of your own laptop will work too - we just need show web pages. But do make sure your browser can display web pages properly during the setup time.
🔴 IoT Workshop System Setup
The Netis network router and Raspberry Pi have been pre-configured to specific setup to work together. Also during actual IoT Workshop sessions, the sample code has the proper wifi and mqtt credentials, so just upload the IoT device (participant's NodeMCU board), and it should work.
The Raspberry Pi runs a MQTT broker/server to facilitate the message queue between NodeMCU and Raspberry Pi, also it runs IoTCS client code to communicate IoT data and messages to IoTCS cloud instance. They are all pre-configured to work out of box, except a step documented below to refresh security provision if we changed IoTCS cloud instance.
If there are any issues that you need to re-configure router or Raspberry Pi, please contact Raymond Xie at yuhua.xie@oracle.com, to get the login credentials. It is very unlikely that you need re-configure setup, and definitely involve Raymond directly when you have to re-configure at your conference venue, so we know how to roll back to original state for next city.
The first thing is to connect conference network connection wire to the router, start up the router, and wait for its AP network "oc-iotws" to be available.
AP: oc-iotws / IoTWorkshop
IP range: 192.168.20.x
Then you can connect your computer to the "oc-iotws" WiFi network, with "IoTWorkshop" as the WiFi password. Once you are on "oc-iotws" wifi network, please check you have Internet access by going to a public website. You should have direct Internet access, without any hotel or conference splash page asking for another credential.
If there is any security setup blocking your computer to have direct access to Internet, stop here and raise the issue to conference organization to bypass such security setup.
The Raspberry Pi should be connected to router over an Ethernet to ensure reliable network connection. Once wired to router, the Raspberry Pi should get a fixed IP address: 192.168.20.251. The Router is configured to reserve that IP address for the Raspberry Pi.
The Raspberry Pi is also configured to get WiFi connection from the "oc-iotws" with fixed IP address at 192.168.20.250. This is for backup purpose (e.g. you've lost the Ethernet cable connecting Raspberry Pi to router). If using "wifi" option, participants need to change the MQTT host in the sample code to 192.168.20.250.
Updated on August 5th, 2017
For all the events after August 5, we have a new IoTCS instance as the previous instances used for earlier events have expired. Since the Raspberry Pi was provisioned to work with those older IoTCS instances, you need to do this step to update the Raspberry Pi with new security provision to work with the new IoTCS instance.
Login Raspberry Pi by: ssh pi@192.168.20.251
Change directory to: cd iot-workshop
Update content by: git pull
Restart Raspberry Pi by: sudo reboot
After you have started up Raspberry Pi, wait for about 30-60 seconds, as there is some setup to start IoTCS client application automatically after some time delay. Then you should log in IoTCS instance and go to "Messages" page, check "Refresh every 5 seconds", and observe the message refresh. Turn the "rotary angle switch" on the GrovePi, and you should see the "angle" reading changes. This step is a quick test, to ensure Raspberry Pi has proper Internet connection, and the IoTCS client application has started up properly to work with IoTCS instance.
If you do not see the "angle" value being updated in IoTCS instance, please log in to Raspberry Pi by:
ssh pi@192.168.20.251
and restart the Raspberry Pi by:
sudo reboot
Sometimes, IoTCS client application starts too early before the router actually gains Internet access. That will lead to client application in a "bad" state. After you verify Raspberry Pi has Internet access by pinging a public website, a reboot of Raspberry Pi would resolve the issue.
Sometimes, when Raspberry Pi is offline for too long, the "time" could be out of sync too much which causes the NTP no longer works. So to check this situation by type "date" on command line and the data time should be correct, to ensure the IoTCS client code can start up properly. If the data and time appears incorrect, please restart NTP sync service on Raspberry Pi:
sudo ntpd -gq
sudo /etc/init.d/ntp restart
That will try to sync time with NTP time server. After a while, check with "date" command again, to ensure you have got correct time on Raspberry Pi.
To properly shutdown Raspberry Pi
Raspberry Pi is a computer, and you don't shut down computer by just pulling the power plug. If Raspberry Pi is not shut down properly, the SD card could be corrupted which leads to problem in its future tours.
To shutdown Raspberry Pi, log in (ssh pi@192.168.20.251), and issue this command:
sudo shutdown -h 0
then wait for about 15-20 seconds, and you can pull the power cord.
You must contact Raymond Xie at yuhua.xie@oracle.com, before the event, to add you in the IoTCS system, so that you can show the messages in IoTCS instance to participants.
iotcs instance: https://129.150.89.67/ui/?root=home (please ask Raymond for the login credentials)
Identity Domain: usoracle40705
Note: please contact Raymond at yuhua.xie@oracle.com to add your email for your access
After you login IoTCS console, please go to "Applications" -> "Oracle Code" -> "Data and Explorations" -> "Messages" tab, check "Auto Refresh Interval" to continually refresh the messages.
This link will let you go to message page directly:
-
Why IoT Workshop session - help participants to learn IoT and set up development environment to program an IoT hardware device; show participant about Oracle IoT Cloud Service and how it accepts IoT data.
-
NodeMCU board - A micro-controller with built-in WiFi chip, inexpensive yet very useful IoT device for prototype. It can be programmed with Arduino using C/C++ language, or Lua script. Less than $10, but practically an arduino board + wifi sheild. Lots of online resources and projects for participants to get started with many IoT projects.
-
Raspberry Pi and GrovePi sensors Raspberry Pi is a miniature computer, which runs Raspbian (official OS), or many other OS images. Grove system is a great generic connector design for hooking up various sensors and components to Raspberry Pi or other boards without using jumper wires or soldering - great for quick prototypes.
-
MQTT protocol A lightweight protocol especially suited for IoT implementation. It uses pub/sub programming model, to relay information across system, network, firewall, etc. to loosely couple various systems.
If the Internet connection simply does not work, we can still proceed with IoT Workshop session to set up the development environment for participants to program hardware device.
Experiment #1 does not require any network. It just blinks some LED lights to confirm that the development environment is setup properly, and participant can program NodeMCU device now.
Experiment #2 does not require Internet connection, and can just utilize the local WiFi network of "oc-iotws". Since the MQTT broker is run on Raspberry Pi, which is under oc-iotws network, it can be accessed by NodeMCU as it will be on the same network.
Experiment #3 - this will require Internet connection! If Internet fails, we just can not complete this exercise. The code on NodeMCU is essentially very similar to experiment #2, it just publishes message to a different MQTT channel that IoTCS client code on Raspberry Pi will pick up, and then forward to IoTCS cloud instance.
🔴 Pac-Man on a String Game Setup
For background about the build and game mechanism, you can check out this instructable page: http://www.instructables.com/id/Pacman-on-a-String/
Watch the videos - video 3 and video 4 as mentioned above, to familiarize yourself on the game.
Connect the Switch to conference network drop, and connect your computer using Ethernet cable to the Switch. Make sure your computer can go to Internet without being blocked by conference or hotel splash page (such as inputting a passcode, or accepting a term conditions).
This Switch will also be used by Pac-Man on a String game box to send game events and scores to Oracle backend. There is no way for the game box to bypass security check, so please make sure you have direct Internet access from the Switch, without any splash page asking for passcode, etc.
If your laptop computer is not able to connect to Internet directly without any hurdles, stop here and raise the issue to Oracle coordinator onsite. Please DO NOT input any passcode or accept terms/conditions on the computer, as that computer is an equipment for testing direct Internet connection.
Your computer is recommended to connect to Switch through Ethernet cable all the time, the Scoreboard page showing on your computer, https://apex.oracle.com/pls/apex/f?p=pacman, has logic to receive game events and scores from Internet, so it is important to have a reliable Internet connection.
-
Put the LED strip onto the tripod, so it stands tall, with bottom portion of LED strip running on the table top.
-
Connect the LED strip to game box - please align the marker so you can plug it in properly.
-
Connect the game box with a network cable to the network switch. Please ensure step 1 above has verified a direct Internet connection. The game box runs an Arduino Mega micro-controller, and it can not accept terms/conditions or input passcode. We need straight Internet connection here.
-
On your computer, you can go to this webpage for display the Scoreboard and Leaderboard: https://apex.oracle.com/pls/apex/f?p=pacman. After you get to the ScoreBoard / LeaderBoard page, the default value in the dropdown is "Global Ranking", which shows the Leaderboard of all events around the world. That page is view-only Leaderboard. To play and record game at your event, please select your city on the dropdown list, to start recording games played in your city. Press the button on the game box to start the game. The game lasts for about 50 seconds, and the LED turns to rainbow color to indicate the end of a game.
-
Now, connect the power to the game box, and LED strip will light up. After about 10 seconds, the game box will start auto-play mode, and you should see / hear scoring on Scoreboard on the laptop.
-
To start a new game for an actual player, press the button on the game box, and you hear a special sound on the Scoreboard, and game time (green bar) starts countdown. When a game is over, an input box and a button will appear on score board. Please input player name, and click "Save Game Score" button.
It is important to click the button, not just an Enter key. Also you have got only 15 seconds to save the score, Pac-man will kick in auto-play mode after 15 seconds - the input box and save button will disappear at that time.
Press the button on the game box to wake it up from auto-play mode, so a player can start game and take over the control of game movement.
-
The game box uses Arduino Mega board to run entire game logic (written in Arduino, a simplified version of C language), it also reads Joystick controller input, and controls the LED lighting. There are 5 different colors of LED dots, representing gems (emerald, sapphire, amethyst, gold), and running red dots as wasp (which can sting you). All LED dots are programmed to appear or disappear at random location and random time.
-
You control a 5-LED segment to move around by pushing joystick UP and DOWN. You collect gems to score by pushing joystick LEFT at the right location (center dots of 5-LED segment has higher score points), and run away to avoid being stung by wasp or proactively attack it to score, by pushing joystick RIGHT at the right moment.
-
Arduino Ethernet shield is in charge of communication to MQTT broker on Internet. Whenever you start game, collect a gem and score(how many points), stung by wasp (and losing points), and game times up, all such game events and scores are being published at real-time.
-
Scoreboard and Leaderboard web page is developed using Oracle Apex, with special MQTT code embedded on the Apex web page. So whenever a game event and score points happen, it is reflected on the Scoreboard real-time, with sound and score update.
-
When game is over, you have a chance to save your play and score to be published on the Leaderboard. Your game score is saved in the Oracle Apex backend. You can view your ranking in your city, and among all events globally.
The conference network is always an uncertainty. If your laptop can reach Scoreboard page, but no sound or no score update when playing game, please check if the network has blocked those not-well-known ports, using "nc" or "nmap" command:
nc -zv m11.cloudmqtt.com 13647
sudo nmap -v -sU m11.cloudmqtt.com -p13647
If the physical game box/LED lights seems to freeze, you can just unplug and plug back the power line to reset. It could be a network issue preventing the MQTT publish call. By resetting, hope we can get a good network connection at the second try.
Also due to the shipment, some connection in the game box could become loose. Take out the bottom layer of the box, and you can touch those electric tapes around the connectors to make them better connected.