diff --git a/README.md b/README.md index baeea83..014f1dd 100644 --- a/README.md +++ b/README.md @@ -1,96 +1,180 @@ -Mycroft GUI +Mycroft GUI =========== -The KDE-based visual interface for working with [Mycroft](https://github.com/MycroftAI/mycroft-core). For more on the Mycroft Skill side, see the [initial Mycroft Core GUI PR](https://github.com/MycroftAI/mycroft-core/pull/1899). +Graphical User Interface powered by Qt and Kirigami for [Mycroft AI](https://github.com/MycroftAI/mycroft-core) -# Getting Started +_______________________________________________________________________ -## Foolproof Setup Instructions(tm) +- [Getting Started](#getting-started) + + [General setup instructions](#general-setup-instructions) + + [Virtual environment setup instructions](#virtual-environment-setup-instructions) +- [Usage](#usage) + + [Local environment](#local-environment) + + [Remote environment](#remote-environment) +- [Development & Contributing](#development-contributing) + + [Contributing to Mycroft GUI API](#contributing-to-mycroft-gui-api) + + [Developing skills with an User Interface](#developing-skills-with-an-user-interface) +- [Troubleshooting](#troubleshooting) + - [Debugging Mycroft GUI](#debugging-mycroft-gui) + +_____________________________________________________________________________________________ + +## Getting Started + +The following guide will provide a set of instructions to get you started with installing Mycroft GUI on your system. *Note:* All non virtual environment setups should generally follow the [General Setup Instructions](#general-setup-instructions) steps. + +### + +### General Setup Instructions + +The interactive Installation script supports installation on KDE Neon, K/Ubuntu 20.04 & Manjaro Linux, It also supports installation and building on other distributions and platforms but system dependencies will be have to installed manually as mentioned in the Installation Script. + + + +1) Fetch Repository and Run Installation Script + + ```@bash + cd ~ + git clone https://github.com/mycroftai/mycroft-gui + cd mycroft-gui + bash dev_setup.sh + ``` + +2) Running Mycroft GUI: + + ```@bash + mycroft-gui-app + ``` + +### Virtual Environment Setup Instructions 1) Download and Install [VirtualBox](https://www.virtualbox.org/wiki/Downloads) -2) Download an ISO from [KDE Neon Developer Edition, Git Unstable](https://neon.kde.org/download). Any build >= 2057. -3) Open VirtualBox and create a Neon installation - TODO: More detailed installations? + +2) Download Latest (Any Supported) Distribution ISO. + +3) Open VirtualBox and create a system installation + 4) Within the VM, open a terminal session and type: - * ```cd ~``` - * ```sudo apt-get install git -y``` - * ```git clone https://github.com/mycroftai/mycroft-gui``` - * ```cd mycroft-gui``` - * ```bash dev_setup.sh``` + + ```@bash + cd ~ + git clone https://github.com/mycroftai/mycroft-gui + cd mycroft-gui + bash dev_setup.sh + ``` + 5) (Optional) Customize Plasma settings for GUI debugging purposes + * Disable screensaver - Click the > icon, type: Screen Locking - Untick "Lock screen automatically after:" - Click OK -6) Run and configure - * ```mycroft-gui-app``` - * Click on the hamburger menu in the lower left - * Select 'Settings' - * Enter the IP address of your device. If your device is at 192.168.2.2, enter 'ws://192.168.2.2' - * Close - -## Normal use - -1) Invoke using ```mycroft-gui-app``` -2) Click *Start* button in the middle of the window - Note: Boot your device or run ```./start-mycroft.sh all && ./start-mycroft.sh enclosure``` prior to doing this. +6. Running Mycroft GUI: + + ```@bash + mycroft-gui-app + ``` + +## + +## Usage + +Mycroft GUI can be used on an Local Environment as well as a Remote Environment + +### + +### Local Environment + +Note: Boot your device or run `./start-mycroft.sh all` + +1) Invoke using ```mycroft-gui-app``` in any terminal, or Mycroft icon from your desktop application launcher. + +2) Click *Start* button in the middle of the window if Autoconnect is disabled + 3) Talk to your Mycroft! -After any code changes (if you are developing) or git pull, simply rerun ```bash dev_setup.sh``` to rebuild. - - -## QML synchronization - -At this point, the paths to skill QML on the Mycroft must precisely match the path on the mycroft-gui-app host machine. The -simplest way to achieve this is to run rsync. This simple script can perform this synchronization, hanldling synchronization -with different devices (e.g. for a developer who does work both at home and at an office). - -**sync.sh** -```bash -function is_online() { - ping -q -w 1 -c 1 "$1" > /dev/null - if [ $? -eq 0 ]; then - rsync -av pi@$1:/opt/mycroft/skills/ /opt/mycroft/skills/ - echo "Synched!" - return 0 - else - return 1 - fi -} - -# Attempt sync with office Mark 1 -is_online 10.10.41.86 -if [ $? -ne 0 ]; then - # Attempt sync with house Mark 1 - is_online 192.168.2.165 -fi -``` - -## Gotchas - -* For a Mark 1, but sure to disable the firewall on the Raspberry Pi. You can do this via ```sudo ufw disable``` -* Generally, the GUI interaction is managed by an enclosure-specific skill that orchestrates things. For example, the Mark 2 uses skill-mark-2. -* Lightweight debugging can be done from Mycroft's CLI. You can see commands being sent to GUI clients by hitting Ctrl+G within the CLI -* Multiple GUIs can safely run against a single Mycroft Core instance. - -## Debugging Tips - -* Debug output can be seen by running the mycroft-enclosure directly from inside an SSH session. On a Mark 1: - - SSH to the Mark 1 - - ```sudo service mycroft-enclosure-client stop``` - - ```sudo su mycroft``` - - ```mycroft-enclosure-client``` - This will start the client and show Debug() messages on the console. - - -## Skill Testing - -```bash -cd /opt/mycroft/skills -git clone -b newapi https://github.com/AIIX/skill-wikidata -cd # -cd mycroft-core -source .venv/bin/activate -cd /opt/mycroft/skills/skill-wikidata -pip install -r requirements.txt -``` +### Remote Environment + +Note: Remote device / server must have mycroft services running or `./start-mycroft.sh all` on remote device / server + +1. Invoke using `mycroft-gui-app` in any remote terminal session, or Mycroft icon from your remote desktop/platform application launcher. + +2. Configuring Mycroft GUI for externally hosted Mycroft-Core: + + - Click on the hamburger menu in the lower left + + - Select 'Settings' + + - Enter the IP address of your device. If your device is at 192.168.2.2, enter 'ws://192.168.2.2' + + - Close + +3. Click *Start* button in the middle of the window if Autoconnect is disabled + +4. Talk to your Mycroft! + +5. Additional Notes: + + - For Externally Hosted Mycroft-Core, one would require to sync skills, one can simply use the provided sync script from the repository to perform a sync + + - Run `bash sync_skills.sh 192.168.1.1 [replace with your remote ip] ` + + - For Externally Hosted Mycroft-Core, but sure to disable the firewall on the Raspberry Pi. You can do this via `sudo ufw disable` + + - Generally, the GUI interaction is managed by an enclosure-specific skill that orchestrates things. For example, the Mark 2 uses skill-mark-2. + + - Lightweight debugging can be done from Mycroft's CLI. You can see commands being sent to GUI clients by hitting Ctrl+G within the CLI + + - Multiple GUIs can safely run against a single Mycroft Core instance. + +## + +## Development & Contributing + +Users & Developers can contribute in advancement of Mycroft GUI in several ways, below mentioned methods will help you identify contribution targets. + +### Contributing To Mycroft GUI API + +Mycroft GUI API is the protocol layer designed to talk and integrate with Mycroft Core Services, It handles various functions some of which include setting, managing and parsing session data and handling delegate activities for skill instances, API Implementation documentation can be found at: + +- [Transport Protocol Documentation](https://github.com/MycroftAI/mycroft-gui/blob/master/transportProtocol.md) + +- [Enclosure API Implementation - Mycroft Core](https://github.com/MycroftAI/mycroft-core/blob/dev/mycroft/enclosure/gui.py) + +### Developing Skills With An User Interface + +Mycroft enabled devices with displays such as the Mark II, KDE Plasmoid provide skill developers the opportunity to create skills that can be empowered by both voice and screen interaction. The display interaction technology is based on the QML user interface markup language that gives you complete freedom to create in-depth innovative interactions without boundaries, A detailed documentation on getting started with developing skills with an user Interface is available at [Mycroft Documentation - Displaying Information](https://mycroft-ai.gitbook.io/docs/skill-development/displaying-information/mycroft-gui) + +## Troubleshooting + +Having trouble or facing issues with Mycroft GUI ? You can use the below guide to debug Mycroft GUI + +### Debugging Mycroft GUI + +1. **Debugging Mycroft GUI Application:** + + - Run Mycroft GUI application from a terminal + + - Errors should be visible on teriminal output, copy output to a log file + + - Open a relevant issue and post your log file + +2. **Debugging Skills & Session Data**: + + - Start Mycroft CLI client and use ctrl+g to view session data being passed to Mycroft GUI + + - For more detailed logging add { "log_level": "debug"} to your mycroft system configuration + + - More detailed logs can be retrived from "/var/logs/mycroft/enclosure.log" & "/var/logs/mycroft/skills.log" + +3. **Debugging on Remote Device (Example: Mark-1)**: + + - SSH to the Mark 1 + + - Run `sudo service mycroft-enclosure-client stop` + + - Run `sudo su mycroft` + + - Run `mycroft-enclosure-client` This will start the client and show Debug() messages on the console. + +## diff --git a/dev_setup.sh b/dev_setup.sh index b63509c..14d4a54 100755 --- a/dev_setup.sh +++ b/dev_setup.sh @@ -12,69 +12,180 @@ if [ $(id -u) -eq 0 ] ; then return 1 fi +# function to display menus +show_menus() { + clear + echo " " + echo "~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~" + echo " WELCOME TO MYCROFT GUI INSTALLATION SCRIPT " + echo "~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~" + echo " " + echo "Please Note: This is an Interactive script that will take you through a series of installation choices, where you might be required to provide your administrative password to successfully install system dependencies and Mycroft GUI on your system." + echo " " + echo "~~~~~~~~~~~~~~~~~~~~~" + echo " SELECT - DISTRIBUTION " + echo "~~~~~~~~~~~~~~~~~~~~~" + echo "1. KDE NEON" + echo "2. K/UBUNTU 20.04+" + echo "3. MANJARO/ARCH" + echo "4. OTHERS" + echo "5. UPDATE INSTALLATION" + echo "6. EXIT" +} + +read_options() { + echo " " + local choice + read -p "Enter choice [ 1 - 5 ] " choice + case $choice in + 1) neon ;; + 2) kubuntu ;; + 3) manjaro ;; + 4) others ;; + 5) updateinstall;; + 6) exit 0;; + *) echo -e "${RED}Error...${STD}" && sleep 2 + esac +} + +#trap '' SIGINT SIGQUIT SIGTSTP + function found_exe() { hash "$1" 2>/dev/null } -# Package installation -if [ ! -f .installed ] || ! md5sum -c &> /dev/null < .installed ; then - # Update package dependencies whenever this file changes - if found_exe apt-get ; then - sudo apt-get install -y git-core g++ cmake extra-cmake-modules kio-dev gettext pkg-config qml-module-qtwebengine - sudo apt-get install -y pkg-kde-tools qtbase5-dev qtdeclarative5-dev kio-dev - sudo apt-get install -y libqt5websockets5-dev libkf5i18n-dev libkf5notifications-dev libkf5plasma-dev libkf5kio-dev libqt5webview5-dev - else - # TODO: Support for other package managers - echo "You must manually install necessary packages for this platform" - fi - - md5sum dev_setup.sh > .installed -fi - +neon() { + echo "Starting Installation For KDE NEON" + echo "" + echo "Following Packages Will Be Installed: git-core g++ cmake extra-cmake-modules kio-dev gettext pkg-config qml-module-qtwebengine pkg-kde-tools qtbase5-dev qtdeclarative5-dev libqt5websockets5-dev libkf5i18n-dev libkf5notifications-dev libkf5plasma-dev libkf5kio-dev libqt5webview5-dev" + echo "" + echo "Please Enter Authentication For Installing System Dependencies" + sudo apt-get install -y git-core g++ cmake extra-cmake-modules kio-dev gettext pkg-config qml-module-qtwebengine pkg-kde-tools qtbase5-dev qtdeclarative5-dev libqt5websockets5-dev libkf5i18n-dev libkf5notifications-dev libkf5plasma-dev libkf5kio-dev libqt5webview5-dev + build_gui +} -if [[ ! -d build-testing ]] ; then - mkdir build-testing -fi -cd build-testing -cmake .. -DCMAKE_INSTALL_PREFIX=/usr -DCMAKE_BUILD_TYPE=Release -DKDE_INSTALL_LIBDIR=lib -DKDE_INSTALL_USE_QT_SYS_PATHS=ON -make -j4 -sudo make install +kubuntu() { + echo "Starting Installation For K/Ubuntu 20.04 +" + echo "" + echo "Following Packages Will Be Installed: git-core g++ cmake extra-cmake-modules gettext pkg-config qml-module-qtwebengine pkg-kde-tools qtbase5-dev qtdeclarative5-dev libkf5kio-dev libqt5websockets5-dev libkf5i18n-dev libkf5notifications-dev libkf5plasma-dev libqt5webview5-dev" + echo "" + echo "Please Enter Authentication For Installing System Dependencies" + sudo apt-get install -y git-core g++ cmake extra-cmake-modules gettext pkg-config qml-module-qtwebengine pkg-kde-tools qtbase5-dev qtdeclarative5-dev libkf5kio-dev libqt5websockets5-dev libkf5i18n-dev libkf5notifications-dev libkf5plasma-dev libqt5webview5-dev + build_gui +} +manjaro() { + echo "Starting Installation For Manjaro / Arch" + echo "" + echo "Following Packages Will Be Installed: cmake extra-cmake-modules kio kio-extras plasma-framework qt5-websockets qt5-webview qt5-declarative qt5-multimedia qt5-quickcontrols2 qt5-webengine qt5-base" + echo "" + echo "Please Enter Authentication For Installing System Dependencies" + yes | sudo pacman -S git cmake extra-cmake-modules kio kio-extras plasma-framework qt5-websockets qt5-webview qt5-declarative qt5-multimedia qt5-quickcontrols2 qt5-webengine qt5-base + build_gui +} -# Setup the platform file -if [[ ! -f /etc/mycroft/mycroft.conf ]] ; then - if [[ ! -d /etc/mycroft ]] ; then - sudo mkdir /etc/mycroft - fi +updateinstall() { + echo "Pulling Latest Changes From Master" + git pull origin master + echo "Update Completed" + exit 0 +} -cat <