W1773ND/Jarvis

Natural Language User Interface Program with Python

Platform Supported

Language Stats

Repo Stats

Code Stats

Deployments

Activity

Development and Maintenance

Reach Out

Prerequisites

MacOS
Tested on macOS High Sierra, Mojave, Catalina, Big Sur, Monterey and Ventura*
- System Preferences → Security & Privacy → Privacy
- Click + sign and add the preferred IDE and Terminal in the following sections in left pane.
  - Microphone - Required to listen and respond.
  - Accessibility - Required to use key combinations for brightness and volume controls.
  - Camera - [Optional] Required only during face recognition/detection.
  - Automation - Required to control System Events and other apps like Outlook and Calendar.
  - Files and Folders [OR] Full Disk Access - Required for all FileIO operations.

⚠️ Known Issue with pyttsx3 module on macOS Ventura 13.0: This version of macOS does not hold the attribute VoiceAge. Workaround has been raised as a PR

Windows
Tested on Windows 10
- Settings → Privacy
  - Microphone - Required to listen and respond.
  - Camera - [Optional] Required only during face recognition/detection.
  - Unlike macOS, Windows pops a confirmation window to Allow or Deny access to files and folders.
- Install Anaconda or Miniconda, and VisualStudio C++ BuildTools

Setup

Clone this repository or download it from pypi
Run the following commands in a command-line/terminal:
1. python3 -m venv venv - Creates a virtual env named venv
2. source venv/bin/activate - Activates the virtual env venv
3. which python - Validate which python is being used. Should be the one within the virtual env venv
4. chmod +x lib/install.sh - Makes installation file as executable.
5. bash lib/installs.sh - Installs the required modules based on the operating system.
6. python jarvis.py - BOOM, you're all set, go ahead and interact with Jarvis.

Test Peripherals:

Camera: camera.py

Speaker: speak.py

Microphone: mic.py

Speech Recognition: recognizer.py

ENV Variables

Environment variables are loaded from a .env file and validated using pydantic

More on Environment variables

TITLE - Title which Jarvis should address the user by. Defaults to sir
NAME - Name which Jarvis should address the user by. Defaults to Vignesh
SENSITIVITY - Hot word detection sensitivity. Range: 0-1
WAKE_WORDS - List of wake words to initiate Jarvis' listener. Defaults to ['jarvis'] (Defaults to ['alexa'] in legacy macOS)

⚠️ Jarvis has limitations on the wake words as it relies on ML libraries for wake word detection.

RECOGNIZER_SETTINGS - A JSON object that has with customized speech recognition settings.
VOICE_NAME - Name of the voice supported by the OperatingSystem. Defaults to the author's favorite.
VOICE_RATE - Speed/rate at which the text should be spoken. Defaults to the value from pyttsx3 module. Typically 200

To add more voices:

macOS:

System Preferences → Accessibility → Spoken Content → System voice → Manage Voices...

Windows:

Settings → Time & Language → Speech → Manage voices → Add voices

Custom settings for speech recognition

These are customized according to the author's voice pitch. Please use mic.py to figure out the suitable values in a trial and error method.

These settings are added (optionally), to avoid the hard coded PHRASE_LIMIT
Cons in using hard coded PHRASE_LIMIT:

Disables the listener after the set limit even the speaker is actively talking.

Listener will be active until the set limit even after the speaker has stopped talking.

Sample settings (formatted as JSON object)

RECOGNIZER_SETTINGS: '{"energy_threshold": 1100, "dynamic_energy_threshold": false, "pause_threshold": 2, "phrase_threshold": 0.1, "non_speaking_duration": 2}'

Description

energy_threshold: Minimum audio energy to consider for recording. Greater the value, louder the speech should be.
dynamic_energy_threshold: Change considerable audio energy threshold dynamically.
pause_threshold: Seconds of non-speaking audio before a phrase is considered complete.
phrase_threshold: Minimum seconds of speaking audio before it can be considered a phrase - values below this are ignored. This helps to filter out clicks and pops.
non_speaking_duration: Seconds of non-speaking audio to keep on both sides of the recording.

LIMITED - Runs only the main version of Jarvis skipping all other background processes. Enforced based on the number of CPU cores. It can also be enabled with env-var.
CAMERA_INDEX - Camera index that has to be used. Run camera.py to get the index value of each camera.
DEBUG - Boolean flag to enable debug level for logging.

Offline communicator

OFFLINE_PORT - Port number to initiate offline communicator. Defaults to 4483
OFFLINE_PASS - Secure phrase to authenticate offline requests. Defaults to OfflineComm

Features

GIT_USER - GitHub Username
GIT_PASS - GitHub Token
WEATHER_API - API Key from openweathermap
NEWS_API - API Key from newsapi
MAPS_API - API Key for maps from Google
GMAIL_USER - Gmail account username to send and read emails.
GMAIL_PASS - Gmail account password to send and read emails.
ALT_GMAIL_USER - Alternate gmail account username to send an SMS. (GMAIL_USER can be re-used)
ALT_GMAIL_PASS - Alternate gmail account password to send an SMS. (GMAIL_PASS can be re-used)
RECIPIENT - Email address to which the emails from jarvis have to be received.
ROBINHOOD_USER - Robinhood account username.
ROBINHOOD_PASS - Robinhood account password.
ROBINHOOD_QR - Robinhood login QR code
BIRTHDAY - Birth date in the format DD-MM - Example: 24-April
ICLOUD_USER - iCloud account username/email.
ICLOUD_PASS - iCloud account password.
ICLOUD_RECOVERY - Recovery phone number to activate lost mode on a target device - Example: +11234567890
PHONE_NUMBER - To send SMS from Jarvis - Example: +11234567890
ROOT_PASSWORD - System password for your mac to get the system vitals.
WOLFRAM_API_KEY - API Key from wolfram alpha.
ICS_URL - Shared calendar URL to get meetings information from. Should end with .ics
EVENT_APP - To read events from outlook or calendar. Defaults to calendar
💡 When calender is used, the name of the calendar within the Calendar.app should be Jarvis
SPEECH_SYNTHESIS_TIMEOUT - Timeout to connect to the docker container that processes text to speech requests.
- To enable independent speech-synthesis run:

docker run \
    -it \
    -p 5002:5002 \
    -e "HOME=${HOME}" \
    -v "$HOME:${HOME}" \
    -v /usr/share/ca-certificates:/usr/share/ca-certificates \
    -v /etc/ssl/certs:/etc/ssl/certs \
    -w "${PWD}" \
    --user "$(id -u):$(id -g)" \
    rhasspy/larynx

💡 Text to speech is optionally run on a docker container for better voices but the response might be slower. If you don't have docker installed or simply don't want to use it, set the SPEECH_SYNTHESIS_TIMEOUT env var to 0. This is also done automatically if failed to launch a docker container upon startup.

Background scans [Defaults to 1 hour]

SYNC_MEETINGS - Interval in seconds to generate meetings information using ics URL.
SYNC_EVENTS - Interval in seconds to generate events information using calendar or outlook application.

API Features

ROBINHOOD_ENDPOINT_AUTH - Authentication token to access the robinhood portfolio which is generated every hour.
SURVEILLANCE_ENDPOINT_AUTH - Token to access webcam live feed via Jarvis API.
SURVEILLANCE_SESSION_TIMEOUT - Session time out for /surveillance. Defaults to 300 seconds.
STOCK_MONITOR_ENDPOINT_AUTH - Token to add a stock price monitor. (Will soon be made open-source)
TASKS - Runs certain tasks at certain intervals.

[
  {"seconds": 10_800, "task": "remind me to drink water"},  # Runs every 3 hours
  {"seconds": 21_600, "task": "turn off all lights"}  # Runs every 6 hours
]

CRONTAB - Runs scheduled tasks using cron expressions without using actual crontab.

[
  "0 0 * * 1-5/2 find /var/log -delete",
  "0 5 * * 1 tar -zcf /var/backups/home.tgz /home/"
]

VPNServer integration

VPN_USERNAME - Username to create vpn-server. Defaults to profile username.
VPN_PASSWORD - Password to authenticate vpn-server. Defaults to profile password.
VPN_DOMAIN - Domain name for the hosted zone.
VPN_RECORD_NAME - Alias record name to access VPN server.

TV controls - Applies only for LGWebOS

TV_CLIENT_KEY - TV's Client key. Auto-generated when used for the first time.
TV_MAC - TV's mac address. Can be single [str] or multiple [list] mac addresses (to include both wired and wireless macs).

Car Controls - Applies only for JLR vehicles using InControl API.

CAR_EMAIL - Email address to log in to InControl API.
CAR_PASS - Password to authenticate InControl API.
CAR_PIN - InControl PIN.

Telegram Bot integration

BOT_TOKEN - Telegram BOT token.
BOT_CHAT_IDS - UserID/ChatID for a particular user.
BOT_USERS - Usernames that should have access to Jarvis.

Smart Devices

A source file smart_devices.yaml is used to store smart devices' hostnames. Jarvis supports MagicHome lights and LGWebOS TVs.

Setup Instructions

Note: Jarvis currently supports only one hostname for TV but multiple for lights.

The name used in the keys will be the identifier of those light bulbs.
The source file (smart_devices.yaml) should be as following:

bedroom:
  - 'HOSTNAMES'
hallway:
  - 'HOSTNAMES'
hallway basement:
  - 'HOSTNAMES'
kitchen:
  - 'HOSTNAMES'
living room:
  - 'HOSTNAMES'
party mode:  # Light hostnames which needed to be engaged for party mode
  - 'HOSTNAMES'
tv: 'LGWEBOSTV'

Automation Setup [Optional]

Executes offline compatible tasks at pre-defined times without any user interaction. Uses an automation.yaml file as source which should be stored within the directory fileio

Setup Instructions

The YAML file should be a dictionary within a dictionary that looks like the below.

OPTIONAL: The key, day can be a list of days, or a str of a specific day or simply a str saying weekday or weekend when the particular automation should be executed.

Not having the key day will run the automation daily. Date format should match exactly as described below.

06:00 AM:
  day: weekday  # Runs only between Monday and Friday
  task: set my bedroom lights to 50%
06:30 AM:
  day:  # Runs only on Monday, Wednesday and Friday
  - Monday
  - wednesday
  - FRIDAY
  task: set my bedroom lights to 100%
08:00 AM:  # Runs only on Saturday and Sunday
  day: weekend
  task: set my bedroom lights to 100%
09:00 PM:  # Runs daily
  task: set my bedroom lights to 5%

Coding Standards

Docstring format: Google
Styling conventions: PEP 8
Clean code with pre-commit hooks: flake8 and isort

Linting

PreCommit will ensure linting, and the doc creation are run on every commit.

Requirement
pip install --no-cache --upgrade sphinx pre-commit recommonmark

Usage
pre-commit run --all-files

Feature(s) Implementation

Please refer wiki for API usage, access controls, env variables, features' overview and demo videos.

Pypi Package

https://pypi.org/project/jarvis-ironman/

Runbook

https://thevickypedia.github.io/Jarvis/

License & copyright

Licensed under the MIT License

W1773ND / Jarvis