Developer Environment Setup, Smartbike Introduction, & Starting Smart…

…bike (#156)

docs/project-1/iot/codebase-documentation/Codebase-Overview.md

@@ -2,4 +2,84 @@
 sidebar_position: 1
 ---
 
-# Codebase Overview
+# Codebase Overview
+
+```
+├── Archive
+├── Drivers
+│   ├── button_control
+│   │   └── button_control.py
+│   ├── kickr_climb_and_smart_trainer
+│   │   ├── wahoo_device.py
+│   │   └── incline_and_resistance_control.py
+│   ├── fan
+│   │   └── fan.py
+│   └── heart_rate_sensor
+│       └── heartrate.py
+└── scripts
+    ├── start_all.sh
+    ├── start_ ... .sh
+    └── ble-auto-connect
+        ├── ble_auto_connect.sh
+        └── ble_auto_connect.exp
+```
+
+**Repository: [redback-smartbike-iot](https://github.com/Redback-Operations/redback-smartbike-iot)**
+
+The IoT repository is only split across three directories:
+
+1. `Archive` contains old and retired code, research, and documentation.
+2. `Drivers` contains currently used driver code.
+3. `scripts` contains bash scripts used to run driver code.
+
+## Dependencies
+
+Several dependencies are used by the drivers:
+
+- `paho-mqtt` is used for MQTT functionality
+- `gatt` library is used for GATT functionality
+
+`Drivers/lib/` directory contains our in-house library/common code - including:
+
+- `constants.py` for constants used across drivers such as MQTT example topics, upper and lower bounds for valid value ranges, etc.
+- `mqtt_client.py` which contains our standard mqtt client which should be used by all drivers.
+- `ble_helper.py` which is used by drivers to match UUIDs of characteristics & services and convert values to their OP codes.
+- `gatt/` directory which contains the `gatt_linux.py` updated `gatt` library used by some drivers.
+
+Both the in-house and external dependencies help to standardise and streamline code.
+
+## scripts
+
+The `scripts` directory holds our `bash` scripts for running driver code. 
+
+The `start_all.sh` script is the primary Smartbike process script which starts all relevant drivers.
+
+### ble-auto-connect
+
+`ble-auto-connect/` sub-directory contains the `ble_auto_connect` script: it is made up of a `bash` script and `expect` script. To find out more about the `ble_auto_connect` script see the [documentation](../ble-connectivity/BLE-Auto-Connect-Script.md).
+
+## Drivers
+
+Drivers drive the functionality of the Smartbike. They connect, control and read values from a specific Smartbike component. Multiple drivers are used to drive the whole Smartbike.
+
+### button_control
+
+`button_control.py` drives the turning button code and any other buttons.
+
+### kickr_climb_and_smart_trainer
+
+`wahoo_device.py` drives the **KICKR Climb**'s incline control and **KICKR smart trainer**'s resistance control. It also reads the `speed`, `cadence` and `power` values from the KICKR smart trainer.
+
+`incline_and_resistance_control.py` is the starter for the `wahoo_device.py` driver. It takes arguments from the starting script and reads loaded environment variable values.
+
+### fan
+
+`fan.py` drives the **Wahoo Headwind Blueooth Fan**, connecting to and controlling the fan's blowing force.
+
+### heart_rate_sensor
+
+`heartrate.py` drives the **TICKR heart rate monitor**, connecting to and read & publishing the heart rate data from the TICKR.
+
+## Archive
+
+The `Archive` directory holds old and retired code. This includes retired drivers (mostly predefined workout "routines" for the Smartbike), code for remotely connecting to and controlling the Raspberry Pi, a very different and old version of the VR game. It also holds old documentation and research.

docs/project-1/iot/introduction/Developer-Environment-Setup.md

@@ -3,3 +3,41 @@ sidebar_position: 3
 ---
 
 # Developer Environment Setup
+
+Working with the Smartbike requires a few extra tools compared to working on applications like the VR game.
+
+## General Needs
+
+You still require general things like:
+
+- IDE of your choice.
+- [GitHub Desktop app](https://desktop.github.com/download/) or [GitHub CLI](https://cli.github.com) or equivalent.
+
+## Project Repositories
+
+Fork the Redback Operation repositories, and bookmark both the original and personal-forks for ease of access.
+
+- [IoT Repo](https://github.com/Redback-Operations/redback-smartbike-iot)
+- [Documentation Repo](https://github.com/Redback-Operations/redback-documentation)
+- [VR repo](https://github.com/Redback-Operations/redback-smartbike-iot)
+
+Clone the repositories to your PC to be ready for development.
+
+## Tools for the Smartbike & Raspberry Pi
+
+To ease development on the Raspberry Pi it is recommended to prepare the following tools to assist in development:
+
+- [PuTTY](https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html) or equivalent - for accessing the Raspberry Pi.
+- [FileZilla](https://filezilla-project.org/download.php?type=client) or [WinSCP](https://winscp.net/eng/download.php) or equivalent FTP application - for transfering files between your development environment and the Raspberry Pi.
+- Install dependencies such as Python's [gatt library](https://pypi.org/project/gatt/) and [paho MQTT](https://pypi.org/project/paho-mqtt/) - for hints during development.
+
+## Personal Mobile Hotspot
+
+The Raspberry Pi currently (T2 2024) connects to the internet through connecting to someone's personal mobile hotspot on their phone. As long as you have the same SSID and password setup it will be able to connect. **Reach out to your project lead (or if you are the lead read the handover document) for the SSID and password to set.**
+
+## Ready to Start
+
+Ask your project lead for tasks to get started on or...
+
+- See the Planner on Teams for tasks (it is like Trello).
+- [Delve into the code](https://github.com/Redback-Operations/redback-smartbike-iot)

docs/project-1/iot/introduction/Smartbike-Introduction.md

@@ -2,4 +2,123 @@
 sidebar_position: 2
 ---
 
-# Smartbike Introduction
+# Smartbike Introduction
+
+![Smartbike Architecture](../img/architecture/bike-architecture.png)
+
+...
+
+## Makerspace
+
+The Smartbike is kept in the Makerspace under [building HF](https://www.deakin.edu.au/__data/assets/pdf_file/0003/817365/burwood-campus-map.pdf) on the Burwood campus. This is a fairly new space intended for IoT development which gives students access to equipment like soldering irons, 3D printers, laser cutting machines, etc. 
+
+To access the Makerspace you first need to complete the [online induction](https://d2l.deakin.edu.au/d2l/home/1381894) (good chance this link does not work) and then schedule an in-person induction.
+
+The Makerspace is open from 10:00 am to 4:00 pm on weekdays.
+
+## Safety & Rules
+
+Use of the Smartbike has limitations as to ensure safety and follow university rules. The following rules must be followed:
+
+- Follow all rules of the Makerspace.
+- **DO NOT** ride the Smartbike *unless* you have signed the waver.
+- Be respectful of the equipment - it is expensive and some equipment is not owned by members of the team.
+- Ride the Smartbike with caution as it can be unstable.
+
+## Wahoo
+
+The core of the Smartbike is an off-the-shelf indoor exercise bike produced by Wahoo. It is formed by several different smart components which each offer unique and useful functionality.
+
+### KICKR Smart Trainer
+
+![KICKR Smart Trainer](../img/smartbike-photos/kickr-left-side.jpg)
+
+The **KICKR smart trainer** is a central piece of the Smartbike:
+
+- Sensing/simulating **speed**
+- Sensing cycling **cadence**
+- Sensing cycling **power**
+- Actuating pedal **resistance**
+- Connecting to the **KICKR Climb**
+- Connecting to the **KICKR Headwind Bluetooth Fan**
+
+The **VR game** uses the KICKR smart trainer's speed simulation to control the speed of the in-game bike.
+
+The **KICKR Climb** and **KICKR Headwind Bluetooth Fan** also automatically pair with the KICKR smart trainer. The KICKR Climb cannot be controlled directly but rather is a sort of extension of the KICKR smart trainer. The KICKR Headwind Bluetooth Fan can either be paired with the KICKR smart trainer, meaning the sensed speed will determine the power of the fan, or directly connected to and controlled by the **Raspberry Pi**.
+
+**Find out more on the [Wahoo website](https://au.wahoofitness.com/devices/indoor-cycling/bike-trainer-bundles/zwift-bundles/kickr-core-zwift-buy)**
+
+**See its [driver](https://github.com/Redback-Operations/redback-smartbike-iot/blob/main/Drivers/kickr_climb_and_smart_trainer/wahoo_device.py)**
+
+### KICKR Climb
+
+![KICKR Climb](../img/smartbike-photos/kickr-climb.jpg)
+
+The KICKR Climb can alter the **incline** of the Smartbike. It is attached to the front of the bike and can shift it up or down, increasing or decreasing the incline. It can be controlled by a **remote mounted to the handle bars**. It has an incline range from **-10° to 19°** - a total range of **30°** including the **0° (flat) level**.
+
+The KICKR Climb is an extension of the **KICKR smart trainer**. It automatically connects to the KICKR smart trainer and cannot be connected to directly. It could be possible to spoof the connection between the KICKR smart trainer and KICKR Climb to control the KICKR Climb directly but this has not been investigated.
+
+The KICKR Climb's incline control is used by the **VR game** to give *haptic* feedback to the player as they go up and down terrian in-game.
+
+**Find out more on the [Wahoo website](https://au.wahoofitness.com/devices/indoor-cycling/accessories/kickr-climb-buy)**
+
+**See its [driver](https://github.com/Redback-Operations/redback-smartbike-iot/blob/main/Drivers/kickr_climb_and_smart_trainer/wahoo_device.py)**
+
+### KICKR Headwind Blueooth Fan
+
+![Headwind Fan](../img/smartbike-photos/headwind-fan.jpg)
+
+The KICKR Headwind Bluetooth Fan is positioned in front of the Smartbike and blows air at different strengths to simulate a headwind. It can be paired with either the **KICKR smart trainer** or **TICKR heart rate monitor** to automatically blow proportional to the speed of the bike or heart rate of the user. Alternatively, the `fan` driver can be used to control the fan directly.
+
+**Find out more on the [Wahoo website](https://au.wahoofitness.com/devices/indoor-cycling/accessories/kickr-headwind-buy-au)**
+
+**See its [driver](https://github.com/Redback-Operations/redback-smartbike-iot/blob/main/Drivers/fan/fan.py)**
+
+### TICKR Heart Rate Monitor
+
+![TICKR Heart Rate Monitor](../img/smartbike-photos/tickr.jpg)
+
+The TICKR heart rate monitor is a heart rate monitor which is **strapped around the chest**. It must be directly connected to the **Raspberry Pi** and automatically goes to sleep after **30-seconds** of non-use. It senses heart rate in **beats per a minute (BPM)**.
+
+Connecting to the TICKR heart rate monitor can be tricky due to its short awake time. 
+
+1. To awaken the TICKR press both thumbs against the diodes on the back of the TICKR - it has awaken when the LEDs turn on. 
+2. To connect to the Raspberry Pi, run the driver code and wait for the blue LED to change from flashing once a second to twice a second.
+3. The TICKR is connected and the LEDs will switch off in about 30-seconds but the connection will persist.
+
+**Find out more on the [Wahoo website](https://au.wahoofitness.com/devices/heart-rate-monitors/trackr-heart-rate-buy)**
+
+**More information on the [TICKR's LEDs](https://support.wahoofitness.com/hc/en-us/articles/204281534-What-do-the-TICKR-LEDs-mean)**
+
+**See its [driver](https://github.com/Redback-Operations/redback-smartbike-iot/blob/main/Drivers/heart_rate_sensor/heartrate.py)**
+
+### Wahoo Cadence Sensor [Redundant]
+
+![Cadence sensor](../img/smartbike-photos/cadence-sensor.jpg)
+
+The Wahoo cadence sensor is attached to the right pedal of the Smartbike. While it was initially developed for, it was discovered that the **KICKR smart trainer** has the same native capabilities, automatically sensing cadence, and hence the Wahoo cadence sensor is **redundant**. It is possible that the Wahoo cadence sensor has reduced latency. If this is the case it would be worthwhile reintegrating it.
+
+**Find out more on the [Wahoo website](https://au.wahoofitness.com/devices/bike-sensors/wahoo-rpm-cadence-sensor)**
+
+**See its [driver](https://github.com/Redback-Operations/redback-smartbike-iot/blob/main/Drivers/cadence_sensor/cadence.py)**
+
+## Raspberry Pi
+
+![Raspberry Pi](../img/smartbike-photos/raspberry-pi-attached.jpg)
+
+The Raspberry Pi is the central controller of the Smartbike system. The above components can be connected to and controlled by the Raspberry Pi. To **interface with applications**, the Raspberry Pi is connected to the internet and uses a **MQTT broker**. The Raspberry Pi can be connected to using **SSH**, a **monitor** or even over **VNC**. 
+
+*To login to the Raspberry Pi ask your project lead for the credentials (or if you are the project lead - see the handover document).*
+
+### Turning Buttons
+
+![Turning Button](../img/smartbike-photos/left-button.jpg)
+
+Connected to the Raspberry Pi is two turning control buttons. The buttons are mounted on the handle bars and intended to be pressed when a user wishes to turn in-game. They are connected to **pins 11 and 12** on the Raspberry Pi's **GPIO** pins.
+
+**See the [button's driver](https://github.com/Redback-Operations/redback-smartbike-iot/blob/main/Drivers/button_control/button_control.py)**
+
+## Get Ready to Work with the Smartbike
+
+- Setup your [developer environment](Developer-Environment-Setup.md).
+- Learn how to [start the Smartbike](../operation/Starting-Smartbike.md).

docs/project-1/iot/operation/Starting-Smartbike.md

@@ -2,4 +2,47 @@
 sidebar_position: 1
 ---
 
-# Starting Smartbike
+# Starting the Smartbike
+
+The Smartbike can be started from the Raspberry Pi. After being started, the Raspberry Pi will send and receive data over MQTT.
+
+## Before Powering the Raspberry Pi
+
+Before you turn the Raspberry Pi on, do the following:
+
+1. Power on the Smartbike devices
+2. Ensure the wireless signal on the KICKR Climb remote is solid (paired)
+
+![KICKR Climb paired](../img/smartbike-photos/climb-remote-locked.jpg)
+
+*If not - hold down the remote's button until quickly flashing and ensure the KICKR smart trainer is powered*
+
+3. Press the button on the KICKR Climb remote to unlock it
+
+![KICKR Climb remote](../img/smartbike-photos/climb-remote-unlocked.jpg)
+
+4. Ensure that your PC and the Raspberry Pi are connected to your personal mobile hotspot
+
+## Start the Raspberry Pi
+
+5. Power the Raspberry Pi
+6. Connect via `SSH`, `VNC`, or monitor
+
+*The Raspberry Pi can be `SSH` into using port `22` and its hostname: `bike000001`.*
+
+7. Login to the Raspberry Pi
+
+*Ask your project lead for login credentials (or if you are the lead - check the handover document).*
+
+8. Awaken the TICKR heart rate monitor - follow instructions in the [Smartbike Introduction](../introduction/Smartbike-Introduction.md) document
+9. Start the Smartbike process by running the follow command in the home directory:
+
+```
+bash iot/scripts/start_all.sh
+```
+
+*The KICKR smart trainer BLE indicator light should turn solid:*
+
+![BLE indicator light](../img/smartbike-photos/kickr-connected.jpg)
+
+*If BLE errors are encountered see the [ble-auto-connect script](../ble-connectivity/BLE-Auto-Connect-Script.md) or [BLE connectivity fix document](../ble-connectivity/BLEConnectivityFix.md).*