This is the social distance project description. Solution Video

As work environment re-opens after the COVID-19 pandemic peak, a new normal will have to be defined. While we all hope that there will not be another pandemic in this proportion, we are all aware that it is extremely likely that similar situations will recur.

Unfortunately, companies nowadays have no means of reinforcing preventive measures in the workplace, such as wearing facial masks or maximum number of people in a room, let alone tracking the times and locations within their sites that an employee or visitor has passed, once he/she reports being infected.

In order to address this challenge, our team proposes building a platform capable of capturing and analyzing information from multiple sources, giving visibility about the issues listed above.

Platform will be composed of multiple blocks, implementing an architecture that allow the platform to expand. There will be three kind of modules:

• Monitoring modules: responsible for capturing information from multiple sources.
• Backend modules: responsible for storing and analyzing information extracting insights from it.
• Frontend modules: responsible for user interaction, platform configuration, alerts and reports.

Webex Teams will be leveraged as the frontend.

Regarding monitoring modules, the following is implemented:

• Detection of people not using facial mask, leveraging video analytic built over Meraki cameras.
• Identification and counting of people in a certain site leveraging Meraki cameras native analytics, Meraki WiFi location APIs and others.
• Tracing people with whom an infected person had contact with in the work environment during the period when he was supposed to have had the virus incubated.

Regarding Frontend Modules:

• Webex Social Bot: responsible to communicate with the facility manager of the office and the users to interact with this Solution.
• We design an easy "normal human/non-IT users" communication system where the social bot tries to understand user needs and helps them with simple step questions to get configurations and or reports done.
• Facility manager can setup Max Room people presence to comply with company regulations, activate Camera Mask Detection and ask current or past information about office status to take proper decisions.
• Employees can talk to the social bot to identify the best days to go to the office according to Occupancy History.
• Social bot send alerts to users in the office and the facility manager whenever people without mask is detected or quantity of people in a particular room reaches a certain threshold.

Regarding Backend modules:

• DB system: reponsible to receive and store data generated by the monitoring modules. Responsible to generate reports for Facility manager and employees to help suport office social distance regulations.
• Dashboard System: Web Based application that provides to the Facility manager the healthy state of the offices.
• Alert System: reponsible to alert facility manager and employees of current social distance out of compliance rules, based on real time information.
• (FUTURE) - Detecting the minimum distance between people in a site (stretch goal), levering video analytics build over Meraki cameras.

Our solution will levegerage the following Cisco technologies

• Meraki Cameras and Access-Point (http://meraki.cisco.com)
• Webex Teams (http://teams.webex.com)

• Marcos Alves maralves@cisco.com - TSS-GVE
• Daniel Vicentini dvicenti@cisco.com - PSE
• Andrey Cassemiro acassemi@cisco.com - SE
• Flavio Correa flcorrea@cisco.com - TSA

Infrastructure Components:

• Linux Server to host applications
• Python applications to exchange information at the Backend, Monitoring Modules and Front End modules
• Influx DB for data storage
• Grafana Server for Dashboard GUI
• A Cloud IaaS service to host all the components - In our project we host it on Digital Ocean Service.
• Cisco Webex Teams Cloud Services as a Frontend for the users
• Cisco Meraki Cloud Services to interact with the necessary information

Cisco Hardware:

• Meraki MV and MR devices to generate Data

Users must have a proper Webex Teams account created and the Webex Teams client (Desktop or Mobile) installed.

Theres are two types of users known by the Frontend system: the regular employess wich are Webex Teams users and the Admin users that are the Facility managers/People responsible for the Social Distance compliance at the offices. The Admin users are also Cisco Webex Teams users.

The Webex Teams users (both admin or regular users) will interact with the social bot which it will understand certain configured commands. When a user chat with the social bot, it will automaticaly understand if a user is or isn't a admin users. After that it will provide users with the available commands for them.

Firts, look for social bot name at the Webex Teams "People" list. After finding it, starts a 1:1 chat room.

• Help: Will provided the known commands for the users depending of his/her role (regular or admin)
• Report Best Days to go to office: this option will tell user what is the best days to go to a room at the office. Users will provide a past day information where social bot will use to generate a data block to compute days of week with lowest Occupancy. Example - past 15 days.

• Configure Room Distancing: define the maximum allowed quantity of people in a certain Room. The maximum information will serve as the threshold for alerts after this condition is reached. The maximum information will impact reporting around out of compliance Social Distancing. Social bot will ask room name and max qty of people in that room.
• Start/Stop Camera (for mask detection): define wich Meraki Cameras will be used to take snapshots and analyze if there's people in the room without Masks. Bot will ask for Camera name.
• Show Running Configuration: this option will show 1) the current configuration wich is the Admin users id; 2) The "Admins Room" name used for the bot to inform admin alerts and 3) the configured rooms with Room Name and Max people quantity defined.
• Show Inventory: this option will show the actual Meraki Devices been used for the system to gather information and interact for Mask Detection in the case of MV Cameras.
• Report historic of Distancing: this option will information by rooms and dates the shifts that Occupancy of rooms where beyond Social Distance Rules, reaching out of compliance. Bot will ask user to provied a past time information to provide the report - example past 15 days.
• Report Mask Detection: thil option will report how many People with no-mask events were detected in the past days. Bot will ask user to provied a past time information to provide the report - example past 15 days.
• Report Tracing: this option will report a list of people that were at the office and rooms with a suspect of contagion in a certain period. Bot will ask userid of suspect and a time frame to investigate the list of users. Example: userid, startdate, end date.

The Following resources will be needed before the installation:

• For Webex Teams social bot will be necessary to create the bot identity. Please check how to create a bot at http://developer.webex.com if necessary.
• The following 4 Webex Teams pieces of information are necessary: bot email, bot token, bot tag, and bot public URL address - This URL should be the public address where this application will be hosted. Any public Internet Source service that hosts aplications and provide public Web access should work.
• A Meraki API-key. The application connects with Meraki Dashboard and Meraki MV API. The API-Key can be generate in the Settings Dashboard at http://dashboard.meraki.com
• The Meraki Organization ID and Network ID to find and connect to Meraki Devices.
• Serial ID of Meraki devices to be used.

• Define a Public Server with the minimun hardware specifications: 1vCPU, 1GB RAM, 25GB Storage.
• Install the following components: Python 3.7, Influx DB Server 1.8, Latest Grafana Dashboard
• Create a directory to git clone this project. Sugestion: mkdir /var/Social
• Git Clone this project to your directory

• Create "socialdistance" database
• Define root users and password
• Define DBuser and password

• Import JSON view from grafana folder: grafana_dashboard_example.json
• Edit Devices and Rooms names according to the used inventory.
• Details of Grafana view in the grafana Folder.

• Go the project directory
• Install necessary libs with the command: pip3 install -r requirements.txt

• Define a Webex Teams Room Name for the Admins/Facility Managers
• Include the social bot name in the room
• Include the admins users in the room
• Have the admins users list, it will be used for the project setup.

• Have the Public Internet IP of your Machine hosting this project
• Login in the DashBoard
• Setup Meraki Wireless to send information: Network-wide->Configure->General->Reporting
• Define the Role: "Wireless event log". Point to Public IP used + port 514. Apply
• Setup Meraki Cameras: Cameras->Settings->Sense->MQTT Broker->Add MQTT Broker.
• Use the following parameters: Eclipse Broker, Mqtt.eclipse.org, Port: 1883, Security None. Apply

Every module of this project shares a common configuration file "config_shared.py". You will need to populate the file with the following information:

• Admin Session: define the list of admins/facility managers example:name@domain.com. If there are many, use commas.
• Admin Room: the Webex Teams Admins rooms name previously defined.
• Webex Bot Session: insert Bot details (WebHooK URL Address, Bot Token, Bot Email and Bot Tag) previously defined.
• Meraki Session: insert Meraki API Key, ORG ID and Net ID previously defined.
• Servers Session: Edit Public IP Address, that will be shared across all modules.
• BD Session: Edit root User/Password and DB user/password createded in the Influx DB system.

The Socal Bot uses a piece of information to map Rooms according to Meraki devices used. The file inventory.py must be edited to include all Meraki devices user for the project.

• Edit DB/inventory.py and include in Json format the followin information:
• "SerialNumber": "XXXX-YYYY-ZZZZ" *Serial Number of Meraki Device
• "Device": "Camera" *Type of Device (Camera or Wifi)
• "Nome": "Camera Name" *A nome for the device - facility manager will refer to a device using this information
• "Location": "RoomName" *Name for a room the device conver. This Name will be used as a match for the configuration of the Social Distance rules (Max People).
• "NetworkID": "L_XXXX" *Network ID of the Meraki Device
• Repeat the proccess to each Device that will be used

With the proper information, the Project is ready to start.

• In the directory of the project, execute: "sh SocialDistance.sh" to start all the modules.

Whenever Meraki network starts to send login / logout information, the project will receive this information and will be storing at the Data Base.

It is necessary to define at least one room and maximum quantity of people in that room. This information will be needed for the reporting functions of the Project and also to generate alerts to admins and users. Use the "config rooms" command with the Social Bot.

Activate at least one camera for Facial Mask Detection to start analyzing it and recording. Use the "start camera" for that.

It is necessary enough data for a proper report quality. We suggest at least one week of data.

Thats it!

The SocialDistance project consists of 4 independent modules that shares information with each other via an API Rest-based model. Each folder of this project has more detail of each piece of code for each module.

This module is the piece of code that interacts with the user via Webex Teams. It will chat with the user depending its role (regular employee, admin) and will execute certain commands that each user are entitled to do.

The Social bot is the piece that talks to all modules in the project. Whenever an admin defines a room compliance situation or activates camera detection, the bot take this orders and send signails to the tracking and facial mask detection modules respectively. When alarms is created such as out of compliance in the room (more people than expected) or people with no mask detected, the Tracking and Mask detection modules send signals back to the bot, who will be in charge to alarm user.

Reporting is done trought the bot also. Whenever a user needs information about the data collected, he/her asks information to the bot, which will ask the report to the Data Base / Report Server and then provide the information to the user in the form of a text message.

This module touches de Influx DB for recording and delivery reports. The MaskDetection and Track modules uses this service to store information and the social bot uses this module to gather the report data.

It receives data and stores it in the Influx DataBase using tables.

• The Trace table which stores data whenever users move in the Meraki network as well as when people is detected via Meraki Cameras.
• The Count table records the summing of people in the office.
• The MaskDetection table records whenever the Camera detects people without Mask in the office.

Besides recording, the Data Storage Module produces reporting of the consolidated data. It can report:

• Historic of Occupancy,
• Best Days to go to the office,
• Tracing of people and,
• History about Mask events.

This module receives information from the Meraki Network, both Cameras and WiFi AccessPoints. It normalizes the information, whenever an user logs in our out or when it is detected from the Network. Its core function is to understand user movement (log in, logout), couting people in the room and detect if the social distance threshold is reached.

If the threshold is reached the tracking module does two things:

• Alerts admins about SocialDistance threshold reached, including picture of the room, asking for action.
• Alerts each user connected to the rooms, asking for action.

The Alert is done by sending certain alert type to the bot, wich will in its turn transform this alert in a Webex Teams message and send it to the room accordingly.

The Facil Mask Detection module is responsible to analyze office images and detect people without Facial Mask. The Module runs whenever the Facility Manager/Admin ask to a particular Camera to do it. At the Social bot, the admin informs Camera Name he/her need to detected faces. After that the Facial Mask Detection system starts, it runs periodic checks in the room, taking a picture and analyzing it for out of compliance events. Whenever it founds it, it will alarm Admins about this. It will also sends event data to be stored for reporting.

Process of each module after start:

Social Bot

• socialbot.py

DB and Report Server

• report.py

Track System

• pysyslog.py
• syslog_parsing.py
• trigger.py

Mask Detection

• mask-detection/app.py

-Can't talk to the bot

• Is the config_shared.py variables correct? (most common problem)
• Are Webhooks from Webex Teams reaching your server? (can be related to the bot tag or URL Problem)
• Is there any Firewall service blocking http webhooks from the Internet?

-No Data being generated

• Is Meraki Networking send syslog data to the application?
• Is MV sending MQTT data to the application?
• Is influxDB running?
• Is InfluxDB user/password correctly configured?
• Is the config_shared.py variables correct? (most common problem)
• Is there any Firewall service blocking MQTT/Syslog from the Internet?

-Reports at the bot replies 'Can't connect to the server'

• Is influxDB running?
• Is InfluxDB user/password correctly configured?

-Reports at the bot replies 'No data'

• Are there enough data?

Provided under Cisco Sample Code License, for details see LICENSE

Our code of conduct is available here

See our contributing guidelines here