GUS - Game for Understanding Social distancing

GUS

Game for Understanding Social Distancing.

What problem are you going to solve?

Social distancing is critical in the effort to control the COVID-19 pandemic. GUS is a “Game for Understanding Social Distancing”. It is designed for use in a classroom environment. The goal of this project is to help kids understand how a virus can move from person to person and the effect social distancing can have on the spread of the disease.

What are you going to build to solve this problem?

GUS is a wearable device (GUS badge) used to simulate the spread of a disease. Each student in the class will receive a GUS badge which will become a node in a bluetooth mesh network. The teacher will have the teacher's badge. GUS hopes to create tangible concepts about unseen viruses that can spread easily.

The simulation uses a very rough approximation of how a virus might spread through a population based on the distance between members of the population. It explores how masks and vaccinations can affect the spread of viruses. It is like a game of tag except you don't know who is "it" and you don't know who has been tagged.

GUS has three modes of operation:

• Classroommode - In classroom mode, the students are assumed to be sitting in a grid pattern, like you would normally have in a classroom. The teacher's badge is used to set the initial conditions such as who is initially infected, who is wearing a mask, and who has received the vaccine. Next the teacher sets the number of rows and how far they are spaced apart. During the analysis phase, the color of the eyes of the GUS badges indicate who is infected and who is healthy.
• GUS Tag mode - In GUS Tag mode, GUS badges are able to determine how close they are to other badges. Students will wear the badges throughout their normal school day while GUS tracks how well they observe the social distancing guidelines. GUS identifies a contact event when two students are in close proximity. At the end of the day the results can be analyzed. The teacher uses the teacher's badge to explore the social distancing behaviors of the class.
• GUS TagLive mode - This is the same as GUS Tag mode except the badges show who is healthy and who is infected in real time. It gives the student instant feedback of when they got too close to an infected student. Plus it makes for a better demo video.

GUS's goal is not to provide a classroom curriculum. The goal is to provide teachers with a tool to open the discussion about social distancing and to do so in an interesting way.

Goals

• Create a useful educational tool.
• Use nRF5340DK
• Learn about Bluetooth Mesh networks.

Network

The GUS network is a Bluetooth mesh network consisting of one teacher's badge client node and two or more GUS badge server nodes. Provisioning is done using the Nordic nRF Mesh smartphone app. I built up nine GUS badges and except for the distance checking I saw no performance degradation between two or nine nodes. My distance checking scheme uses a round robin approach. Adding nodes increases the amount of network traffic and decreases the frequency that a node reports back to the teacher. The practical limit of how many badges could be managed could be much higher.

USER INTERFACE

GUS Teacher's Badge

The display on the teacher's badge has three pages: Badges, Config, and Analysis. The three buttons at the top are used to select the desired page.

• Scan - queries the mesh network for GUS badges and adds the names assigned to each of the badges to the name list scroller control on the left.
• Identify - causes the "eyes" of the selected badge to blink.
• Virus, Mask, and Vaccine are checkboxes use to set and show the state of the selected badge. The names in the name list are preceded with special characters to indicate Virus (star), Masked (wifi), or Vaccine (plus).
• Edit Name displays a keyboard that allows the teacher to assign a new name to a badge. A list of common names are used as defaults.

• The dropdown control allows the teacher to select between Classroom,GUS Tag, and GUSTagLive modes.
• The Rows number control specifies the number of rows the class is organized into for the Classroom simulation.
• The Space number control specifies the space separating the students for the Classroom simulation.
• The Rate number control specifies the rate of infection and affects both modes. Increasing the infection rate increases the speed that the infection spreads. An infection rate of 1.2 is normally associated with the COVID-19 virus.

• The Record button is not displayed in classroom mode. Clicking it begins recording badge contacts. While recording, "infections" is updated with the total number of infections as they happen. The progress bar indicates the percentage of infections. Clicking Record again stops recording.
• << (rewind), > (play), and >| (step) allow either the Classroom simulation or the GUS Tag mode recording to be reviewed. The eyes of the GUS badges change from green to red to indicate the spread of infections.

GUS Badge

The GUS badge indicates its current state using its two "eye' R, G, B LEDs:

Left    Right    Description
RGB     RGB      Identify - Flashing in Red, Green, and Blue
Green   Green    Healthy, no mask, no vaccine
Green   Yellow   Healthy, with mask
Blue    Blue     Healthy, with vaccine
Blue    Yellow   Healthy, with mask and vaccine
Red     Red      Infected, no mask and no vaccine
Yellow  Red      Infected, with mask
Blue    Red      Infected, with vaccine
Yellow  Yellow   Infected, with mask and vaccine
Off     Off      Badges are inactive

DEMONSTRATION

The video demonstrates GUS using paper kids instead of the real thing. It was heavily edited to fit into the specified time limit. It shows the following features:

• Scan for badges
• Edit a badge name
• Tagging a student as having the virus
• Configuring the classroom mode simulation
• Analyzing the simulation
• Tagging students with a mask and the vaccine
• Rerunning the modified simulation
• Configuring GUS Tag Live mode (which shows infections as they happen)
• Recording contacts between students and seeing the effects.

BUILDING THE PROJECT

The code for the project is available on github (see CODE section). There are separate projects for the GUS badges and for the teacher's badge. It also requires installing the Nordic nRF Connect SDK version 1.5.0 (1.5.1 builds but has not been tested).

GUSBadgeProject

Building and downloading the GUS badge code is as easy as following the Nordic instructions on Building and programming a sample application. Just use the GUS badge folder for the Project and for the board name you need to browse to the boards\arm\gus_bl652 folder found in the GUS Project folder.

GUSTeacherProject

Building the GUS Teacher Project requires a couple of extra steps:

• The SDK needs to be modified to support the adaFruit display. Please follow the NOTE: in the README.md file found in the GUS Teacher project.
• The nRF5340 board may need to be prepared before using. Follow the Programming the network sample from SES instructions.

After that the GUS Teacher project can be built and loaded with the same steps as in GUS badge, using GUS Teacher for the project and nrf5340dk_nrf5340_cpuapp for the board name.

Provisioning

Once the GUS badges and teacher's badge are programmed, the mesh network needs to be provisioned using the nRF Mesh smart phone app. The mesh network needs:

• 1 application key
• 1 group name GUS Group

Vendor Model 0x0032 of Element 1 for the Gus_Teacher need the following:

• Bound Application Keys > App Key 1
• Publication > Gus Group
• Subscriptions > Gus Group

Vendor Model 0x0032 for each of the Gus badges need the following:

• Bound Application Keys > App Key 1
• Publication > Gus Group
• Subscriptions > Gus Group

HARDWARE

Teacher's Badge

Construction of the teacher's badge is trivial. Simply plug the Adafruit Display onto the nRF5340DK board, connect a USB power bank to J2, add a 3D printed bezel for the display and a rubber band and you have your Advanced Wearable GUS Teachers Badge.

• Documentation for the nRF5340 Hardware
• adafruit touch shield technical-details

GUS Badge

Building a GUS badge is slightly more complex. The GUS badge is built on a 30x35mm pcb and uses an nRF52832 module (Larid BL652). I would have liked to use an nRF5340 module, but availability was limited at the start of the project. The circuit is simple enough to have all traces except power and ground on one layer which made it easy to build my own PCBs.

• J2 is a serial port interface for debugging
• J3 is the JTAG connection
• The test points are unused except for TP4 which will cause a node reset (remove from mesh network) when shorted to ground.

Power consumption is around 7-10 ma, which is a bit high for coin cell powered device. However the CR2032 battery can supply 220mah which is more than enough for one class period and possibly two. A rechargeable battery might be a better solution.

SOFTWARE

Bluetooth Mesh Model

The GUS VENDOR MODE is a custom mesh model based off of the nRF Connect SDK mesh chat example. The teacher's badge is the client node and the GUS badges are server nodes. The key operations are:

• Sign-In
• Set-State
• Set Name
• Request Report
• Check Proximity

Sign-in is the first operation than needs to be run, but can be run at anytime. It occurs when the Scan button on the GUI is tapped. It provides a way for the client to discover the addresses of all active GUS badge nodes and also retrieves the names associated with them. The teacher's badge publishes a sign-in message and all provisioned and active badges respond with their name.

Teacher          Badge1   Badge2  ...   BadgeN
  Signin----->-----^--------^-------------^       Published signin
     <-------------|                              Reply with name
     <----------------------|                            "
     <------------------------------------|              "

Set-State sets the state for all badges or a specific badge. The state normally refers to health/infected, masked, or vaccinated which lights up the LED eyes to reflect the state. The state can also be identify which causes the LEDs to blink for a limited time or Off which makes the LEDs go dark. At the beginning of a simulation analysis, the teacher's badge publishes "healthy" to all GUS badges then updates the state for each badge that requires a different state.

Teacher             Badge1   Badge2  ...   BadgeN
  >-SS healthy--->----^--------^-------------^      Published set state healthy
  >-SS masked--->-----^                             Set State Badge1 masked
  >-SS infected->--------------^                    Set State Badge2 infected

Set-Name changes the name associated with a badge. It occurs in response to tapping Edit Name in the GUI. The badge name is store on the badge and retrieved at sign-in. The badges also contain a list of common default names that are chosen based on the badge's node address (persistence not fully implemented).

Teacher             Badge1   Badge2  ...   BadgeN
  >-Set Name Bjorn ->----------^                    Name of Badge2 changed to Bjorn

Request Report is a complex operation that combines retrieving the contact information from a badge with initiating a check for badges in close proximity. It occurs in response to tapping the Record button in the GUI when in GUS Tag mode. When a badge receives a Report Request message it sends a reply containing the list of the six most significant recent contacts. It then clears its list of contacts and publishes a Check Proximity message to all other badges. Any badge that sees the Check Proximity message adds the sender's address and the RSSI of the message to its own contact list. By the time the teacher's badge has sent a Report Request to every GUS badge, each GUS badge will have had an opportunity to see if they are in contact with any of the other badges. The teacher's badge sends out Report Requests at a rate of once every five seconds while recording, allowing time for the proximity checks to occur. If there are 10 GUS badges in the network, it will take 5 * 10 = 50 seconds for to retrieve the reports from all badges.

Teacher          Badge1   Badge2  ...   BadgeN
  Report Req->-----^                             Report requested from Badge1
     <-------------|                             Badge1 replies with contacts
                 Proximity--^-------^-----^      Badge1 publishes Proximity, all other
                                                   badges record contact if received.
  Report Req->--------------^                    Report requested from Badge2
     <----------------------|                    Badge2 replies with contacts
                   ^-Prox-<-|->-Prox--^---^      Badge2 publishes Proximity, all other
                                                   badges record contact if received.
...
  Report Req->----------------------------^      Report requested from BadgeN
     <-------------|                             BadgeN replies with contacts
                   ^--------^------Prox-<-|      BadgeN publishes Proximity, all other
                                                   badges record contact if received.
...                                              The process repeats while recording

One comment about Bluetooth Mesh, I had a lot of difficulty understanding how to do what I needed to do. Questions which seemed like they should be simple such as how can the client determine the addresses of the server nodes were hard to find. Fortunately the Nordic team was able to help. But it seems like answers like that should be findable through a web search.

GUI

The GUI uses the LVGL library and the initial code was based mostly from the LVGL Widgets demo. It uses a message queue to keep responsive without affecting other parts of the code. Development of the GUI was greatly accelerated by using Visual Studio 2019 to run the code in a simulator. Many shortcuts were taken to speed up development such as faking a tab dialog using buttons instead trying to find the source of crashing when try to use the tabbed widget. Also, instead of using the proper positioning devices like containers and padding, control positions and sizes were hard coded. So the GUI implementation is not a very good example of how to use LVGL to create a GUI. But the result was fairly decently looking and very responsive (thanks to a fast processor).

Simulation

The simulation assumes that your risk of infection is inversely proportional to the square of distance to an infected person. Also the risk is cumulative, mask wearing greatly reduces the risk of infection when worn by the infected person but only moderately protects the mask wearer, and that a vaccinated person won't get infected and has a reduced chance of spreading the virus.

The simulation code has its own message queue. The code keeps a list of active badges with information such as initial infection state, masked, vaccinated, and total exposure to the virus. It also maintains a list of contacts between any two badges and the distance between them, which affects the level of exposure. The list of contacts can grow rather large potentially affecting response time. The algorithm for calculating the total exposure sometimes requires multiple passes through the contact list, which also could affect the response time. However, the nRF5340 had no problem meeting the processing demands and I never noticed any slow downs.

Both modes of operation, Classroom and GUS Tag modes use the same contact list and much of the same code. Since the Classroom code was developed first it took a more complex approach to processing the contact information. When the GUS Tag mode code was implemented, the contact list ended up being much more organized by time than originally expected, simplifying the processing. The code for the Classroom mode code could be simplified, but so far it doesn't appear to be necessary.

Future Extensions

Given more time there are many more features that could be added. In the current implementation of GUS Tag, no one knows who is infected or who gets infected until the analysis phase. One simple modification would cause the badges to respond in real time if they were too close or if they had just been infected. The contact list contains all contacts that occur, so it is possible to try different scenarios where people are now wearing masks or if different people are initially infected. It would also be possible to search for all contacts a particular badge has made or which badge has made the most contacts. If the processor in the badges were upgraded to an nRF5340, directions between badges could be added, allow the teacher's badge to graphically plot a map of the badges vs time.

OTHER DETAILS

Making the PCB was a fun little project of its own. KiCad was used to do the layout and several things we done to make soldering and milling easier such as removing unneeded pads for the nRF532830 module and making the PCB traces fatter. I followed a YouTube video by TeachingTech on the process to get from a layout to the mill. Here is a 1:15 minute video of the making of the PCB. Actual time was a little under 5 minutes.