Update documentation

CMCRobotics · Feb 5, 2023 · 6630033 · 6630033
1 parent 3506726
commit 6630033
Show file tree

Hide file tree

Showing 7 changed files with 69 additions and 12 deletions.
diff --git a/README.md b/README.md
@@ -1,33 +1,36 @@
-# MicroSquad (a.k.a uSquad)
+# MicroSquad
 
 <!--
 [![Known Vulnerabilities](https://snyk.io/test/github/cmcrobotics/usquad-web-ui/badge.svg)](https://snyk.io/test/github/cmcrobotics/usquad-web-ui)
 -->
 ![Build](https://github.com/cmcrobotics/microsquad/workflows/build-action/badge.svg)
+<!--
 [![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=lucasvanmol_usquad-web-ui&metric=alert_status)](https://sonarcloud.io/dashboard?id=lucasvanmol_usquad-web-ui)
+-->
 
-A Microbit orchestration library based on [Bitio](https://github.com/AdventuresInMinecraft/bitio) : Using a single Microbit as a gateway, control remote Microbits via the radio.
+**MicroSquad** is an Internet of Things orchestration framework focused initially on the [BBC Micro:bit](https://microbit.org/) (a.k.a Microbit).
+To interface with the Microbit, it relies on [Bitio](https://github.com/AdventuresInMinecraft/bitio) : Using a single Microbit as a gateway, one can control remote Microbits over the radio.
 Messages are exchanged using the Influx line protocol (with a small custom parser implemented in micropython)
 
 ![Microbit](https://microbit-micropython.readthedocs.io/en/v1.0.1/_images/happy.png)
 
-**Basic functionalities include :**
-* Broadcast, group and unicast messaging
-* Assigning session identifiers (will be resent with each message from the client)
-* Remotely controlling displays
-* Requesting remote sensor readings (buttons, gyroscope, compass, temperature, votes etc...)
-
+**Basic MicroSquad functionalities include :**
+* Broadcast, group and unicast messaging.
+* Assigning session identifiers (will be resent with each message from the client).
+* Remotely controlling displays.
+* Requesting remote sensor readings (buttons, gyroscope, compass, temperature, votes etc...).
+* Controlling a 3D web-based scene where players can interact.
 
-# Dependencies
+# Software dependencies
 
-For the **uSquad** Gateway :
+For the **MicroSquad** Gateway :
 * Python 3.8+
 * [https://github.com/AdventuresInMinecraft/Bitio](https://github.com/AdventuresInMinecraft/bitio)
 
-For the **uSquad** clients :
+For the **MicroSquad** clients :
 * The provided **uSquad** firmware to upload on each Microbit.
 
-For the **uSquad** Web Interface :
+For the **MicroSquad** Web Interface :
 * The spectacular [Kenney Character Assets](https://kenney.itch.io/kenney-character-assets) under Creative Commons Zero
 
 # How to use it

diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1,23 @@
+# MicroSquad documentation
+
+## Design philosophy
+
+**MicroSquad** combines physical devices with virtual devices through Internet of Things (**IoT**) concepts.
+
+Interactions and readings from the physical world are captured through **Terminals** - i.e. devices such as a Microbit microcontroller (which is equipped with sensors such as buttons, temperature, motion sensors, touch pads) or even a mobile phone (for more complex interactions support).
+
+By combining an interaction logic loop (or **Workflow**), one can use **MicroSquad** to create games and team exercises.
+
+The state of **Terminals** and of the **Workflow** are maintained and made available through a hierarchy of variables and their respective values. These values are made available through an **MQTT broker** and accessible via standard Internet protocols (**TCP** and **Websockets**).
+
+From then on, it becomes possible to create interactive **Scenes**, such as 3D environments where the players of a team game can be represented as 3D avatars, or augmented reality experiences combining virtual and physical elements.
+
+On the **scene**, relying on the same design philosophy, all composing elements (3D characters, decor elements, heads up displays, cameras, lighting) are also represented and interacted with via the **MQTT broker**.
+
+The **MQTT broker** values hierarchy relies on a naming convention called [Homie](https://homieiot.github.io/) - Homie exposes a **device** and **property** model that is compatible with **IoT** software such as **HomeAssistant** - so all **MicroSquad** devices (be they physical or virtual) can be mixed and matched with other home automation devices (such as lightbulbs, smart power sockets etc...).
+
+## Implementation
+
+The following architecture diagram summarizes the organization of a typical MicroSquad setup :
+
+![Architecture](https://github.com/CMCRobotics/microsquad/blob/develop/docs/plantuml/MicroSquad%20Architecture.png?raw=true)
diff --git a/docs/plantuml/Game Management.png b/docs/plantuml/Game Management.png
diff --git a/docs/plantuml/Gateway components.png b/docs/plantuml/Gateway components.png
diff --git a/docs/plantuml/MicroSquad Architecture.png b/docs/plantuml/MicroSquad Architecture.png
diff --git a/docs/plantuml/Microbit Client.png b/docs/plantuml/Microbit Client.png
diff --git a/docs/plantuml/architecture.puml b/docs/plantuml/architecture.puml
@@ -0,0 +1,31 @@
+@startuml MicroSquad Architecture
+title MicroSquad Architecture
+
+actor Player as player
+agent Terminal as terminal
+database "MQTT Broker" as broker
+
+
+agent "Bitio Gateway" as gateway
+
+interface Websocket as websocket
+interface TCP as tcp
+
+package "Game workflow" as workflow
+
+agent "3D Scene Manager" as scene
+
+player ..> terminal : Interacts
+terminal <..> gateway : Read and control terminal state
+websocket <--> broker
+gateway <--> tcp : Update game workflow
+tcp <--> broker
+workflow <--> tcp : Manage game
+scene  <--> websocket : Update game visuals
+
+actor Avatar as avatar
+actor "Virtual Display" as display
+avatar <-- scene
+display <-- scene
+
+@enduml