Merge develop

.github/workflows/build-action.yml

@@ -56,13 +56,13 @@ jobs:
                 context: ./modules/web-ui
                 platforms: linux/amd64,linux/arm
                 push: true
-                tags: ghcr.io/cmcrobotics/microsquad-web-ui:latest
+                tags: ghcr.io/cmcrobotics/microsquad/web-ui:latest
 
-            - name: Push Web UI container to GHCR
+            - name: Push Gateway container to GHCR
               uses: docker/build-push-action@v3
               with:
                 context: ./modules/gateway
                 platforms: linux/amd64,linux/arm
                 push: true
-                tags: ghcr.io/cmcrobotics/microsquad-gateway:latest
+                tags: ghcr.io/cmcrobotics/microsquad/gateway:latest
 

.gitignore

@@ -138,4 +138,8 @@ modules/gateway/src/main/python/microsquad/portscan.cache
 **/*-venv/*
 node/
 node_modules/
+<<<<<<< HEAD
 
+=======
+pnpm-lock.yaml
+>>>>>>> develop

README.md

@@ -1,39 +1,44 @@
-# MicroSquad (a.k.a uSquad)
+# MicroSquad
 
-[![Known Vulnerabilities](https://snyk.io/test/github/lucasvanmol/usquad-web-ui/badge.svg)](https://snyk.io/test/github/lucasvanmol/usquad-web-ui)
+<!--
+[![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.
 
+# Software dependencies
 
-# 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 :
-* The provided **uSquad** firmware to upload on each Microbit.
+For the **MicroSquad** clients :
+* The provided **MicroSquad** firmware to upload on each Microbit. For instance [microsquad.hex](https://github.com/CMCRobotics/microsquad/releases/download/v1.0.microsquad.mpy/microsquad.hex)
 
-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
 
 ## Flash the Microbits
 
 * The Microbit Gateway uses [https://github.com/AdventuresInMinecraft/Bitio](https://github.com/AdventuresInMinecraft/bitio) - Simply download the latest compatible firmware and copy it to the Microbit flash drive to load it as the new firmware.
-* The client firmware is available as a Github release.
+* The client firmware is available as a Github release. For instance [microsquad.hex](https://github.com/CMCRobotics/microsquad/releases/download/v1.0.microsquad.mpy/microsquad.hex)
 
 ## Configure and start Mosquitto MQTT broker
 
@@ -45,6 +50,8 @@ protocol mqtt
 
 listener 9001
 protocol websockets 
+
+allow_anonymous true
 ```
 For a more comprehensive example, consult ``docs/samples/mosquitto.conf``.
 
@@ -55,4 +62,10 @@ From ```modules/gateway```, execute :
 . ./setup-venv.sh
 python -m microsquad.gateway.mqtt
 ```
+## Start the Web UI
 
+From ```modules/web-ui```, execute :
+```bash
+. source-path.sh
+npm run serve
+```

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)

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

docs/plantuml/game-management.puml

@@ -1,4 +1,4 @@
-@startuml
+@startuml Game Management
 
 
 actor "Game Organiser" as Organiser

docs/plantuml/microbit-client.puml

@@ -0,0 +1,46 @@
+@startuml Microbit Client
+autonumber 1.1
+queue "Broker" as broker
+control "Gateway" as gateway
+actor "Player" as player
+boundary "Microbit Terminal" as microbit
+
+activate player
+activate gateway
+
+player -> microbit : Turn on
+
+activate microbit
+
+microbit -> gateway : bonjour
+gateway -> microbit : bonjour
+
+microbit -> microbit : alive()
+loop For ever
+  microbit -> microbit : incoming= poll_messages()
+  alt message
+    autonumber inc A
+    gateway -> microbit : radio_send()
+    loop while incoming
+        microbit -> microbit : message,tags,timestamp = parse_line_protocol()
+        alt For this terminal
+            alt show
+            microbit -> microbit : display()
+            end
+            alt vote
+            microbit -> microbit : vote_particles()
+            end
+            alt emote
+            microbit -> microbit : vote_emotes()
+            end
+            alt buttons
+            microbit -> microbit : read_buttons()
+            end
+        end
+    end 
+  end
+end
+
+deactivate microbit
+
+@enduml

docs/samples/mosquitto.conf

@@ -1,3 +1,6 @@
+# Allow anonymous remote connections
+allow_anonymous true
+
 # Config file for mosquitto
 retry_interval 20
 sys_interval 10
@@ -24,4 +27,5 @@ listener 1883
 protocol mqtt
 
 listener 9001
-protocol websockets 
+protocol websockets 
+allow_anonymous true

modules/client-arm-m0-gcc/.gitignore

@@ -0,0 +1,3 @@
+build/
+yotta_modules/
+yotta_targets/

modules/client-arm-m0-gcc/.yotta.json

@@ -0,0 +1,5 @@
+{
+  "build": {
+    "target": "bbc-microbit-classic-gcc,https://github.com/lancaster-university/yotta-target-bbc-microbit-classic-gcc"
+  }
+}

modules/client-arm-m0-gcc/README.md

@@ -0,0 +1,11 @@
+# How to compile
+
+```bash
+docker run -v `pwd`:/home --rm ghcr.io/carlosperate/microbit-toolchain:latest yotta build
+```
+
+Find the resulting firmware in :
+
+```
+build/bbc-microbit-classic-gcc/source/microsquad-arm0-combined.hex
+```

modules/client-arm-m0-gcc/config.json

@@ -0,0 +1,7 @@
+{    
+    "microbit-dal":{
+        "bluetooth":{
+            "enabled": 0
+        }
+    }
+}

modules/client-arm-m0-gcc/module.json

@@ -0,0 +1,11 @@
+{
+  "name": "microsquad-arm0",
+  "version": "1.0.0",
+  "description": "A MicroSquad client for Microbit v1",
+  "license": "GPLv3",
+  "dependencies": {
+    "microbit": "lancaster-university/microbit#v2.1.1"
+  },
+  "targetDependencies": {},
+  "bin": "./source"
+}