Merge pull request #6 from ray-hrst/devel

Partner meeting demonstration

.gitignore

@@ -1,3 +1,6 @@
+*.cert
+*.key
+*.apk
 webapp/node_modules/
 *venv/
 .DS_Store

README.md

@@ -1,25 +1,79 @@
 # jitsi-temi
-A free and open-source alternative to temi's default video-conferencing application.
+A free and open-source alternative to [temi](https://www.robotemi.com/)'s default video-conferencing application.
 
+This is still a prototype. This project uses MQTT for message transport between the client's web-brower user-interface and robot. It uses [Jitsi-Meet](https://jitsi.org/), a free open-source WebRTC framework, for video conferencing.
 
-## TL;DR
-Install APK onto temi.
+The project consists of 3 components:
+1. **Web Application**. A web-browser application used to tele-operate the robot.
+2. **Android App.** An application that bridges robot commands/events and MQTT messages, which is to be installed on the robot.
+3. **MQTT broker.** [Eclipe Mosquitto](https://mosquitto.org/) open-source MQTT broker.
+
+
+## Folder Structure
+```
+jitsi-temi              Root directory
+├─ android              Android application to be installed on temi
+├─ config               MQTT broker configuration files
+├─ mosquitto            MQTT broker
+├─ test                 Various test scripts
+└─ webapp               NodeJS/Express web server and client application
+```
+
+
+## Repository Structure
+There are 2 main branches: `master` and `devel`. Releases are generated from the `master` branch. All development takes place on the `devel` branch.
+
+
+## Getting Started
+
+### Prerequisites
+* [temi robot](https://www.robotemi.com/)
+* [Android Studio](https://developer.android.com/studio/)
+* Computer/Server with the following installed:
+    * [Docker](https://docs.docker.com/install/)
+    * [Docker Compose](https://docs.docker.com/compose/install/)
+* Client computer with [Chrome](https://www.google.com/chrome/) web-browser
+
+### Build & Deploy Web Application Services
+On your host machine, clone the repository and update submodules:
 ```
-adb connect <ip-address>
-adb install connect.apk
+git clone https://github.com/ray-hrst/jitsi-temi.git
+git submodule update --init --recursive
 ```
 
-Start the MQTT broker and web-server:
+Currently, the hostname is hard-coded into the webapp. Look for a call to the function `connectMQTT()` in `main.js` (somewhere near the end). Replace the value with your machine's hostname/IP-address:
 ```
+hostname -I
+```
+
+From the `root` directory, build and deploy the MQTT broker and web application services:
+```
+cd jitsi-temi/
 docker-compose build
 docker-compose up
 ```
 
-Start the `Connect` app on temi. Type in the IP-address of the MQTT broker and press `Connect`.
+### Install Android App
+Install the Android APK onto your robot, see [instructions](https://github.com/robotemi/sdk/wiki/Installing-and-Uninstalling-temi-Applications) for details. The application is called `Connect`. The Android app is available under [releases](https://github.com/ray-hrst/jitsi-temi/releases). 
+
+To build from source, clone the repository:
+```
+git clone https://github.com/ray-hrst/jitsi-temi.git
+```
+
+From the `android` directory, build the Android app using Android Studio. Alternatively, you can try to build the app from the command line:
+```
+cd android/
+./gradlew build
+```
+You will find the Android APK at `app/build/outputs/apk/debug/app-debug.apk`.
+
+### Usage
+Start the `Connect` app on temi. Type in the `hostname` of your machine into the provided text-field, and press `Connect`.
 
-In your web-browser, type the IP-address of the web-server.
+On a computer connected to the same network as your host machine, open a web-browser and enter your host machine's hostname into the address bar.
 
-If everything is working correctly, you should see your temi's serial number appear. Click it to start tele-operations.
+If everything is working correctly, you should see your temi's serial number appear in the web application. Click it to start tele-operating the robot.
 
 
 ## Attributions

android/README.md

@@ -0,0 +1,11 @@
+# Connect Android Application
+
+This is an Android application built using [Eclipse Paho JavaScript Client](https://www.eclipse.org/paho/clients/js/) for communicating with the MQTT broker, [Jitsi-Meet SDK for Android](https://github.com/jitsi/jitsi-meet/tree/master/android) for video-conferencing, and the [temi SDK](https://github.com/robotemi/sdk) for robot control and event handling.
+
+Important Files:
+* android/build.gradle
+* android/app/build.gradle
+* android/app/src/main/AndroidManifest.xml
+* android/app/src/main/res/values/strings.xml
+* android/app/src/main/res/layout/activity_main.xml
+* android/app/src/main/java/com/hapirobo/connect/MainActivity.java

android/app/build.gradle

@@ -46,12 +46,17 @@ dependencies {
     implementation 'androidx.constraintlayout:constraintlayout:1.1.3'
 
     // Jitsi Meet
-    implementation ('org.jitsi.react:jitsi-meet-sdk:2.5.1') { transitive = true }
+    // https://github.com/jitsi/jitsi-meet
+    // https://github.com/jitsi/jitsi-maven-repository/tree/master/releases/org/jitsi/react/jitsi-meet-sdk
+    implementation ('org.jitsi.react:jitsi-meet-sdk:2.7.0') { transitive = true }
 
     // paho-mqtt
+    // https://github.com/eclipse/paho.mqtt.java
     implementation('org.eclipse.paho:org.eclipse.paho.client.mqttv3:1.2.2')
+    // https://github.com/eclipse/paho.mqtt.android
     implementation('org.eclipse.paho:org.eclipse.paho.android.service:1.1.1')
 
     // temi
+    // https://github.com/robotemi/sdk
     implementation 'com.robotemi:sdk:0.10.55'
 }