From 4ccd7269fdcffb5ed1e5fbe6003c1ba49629cc52 Mon Sep 17 00:00:00 2001 From: madmachinations Date: Sun, 5 Jan 2025 00:47:22 +0000 Subject: [PATCH] Added visual debug mode and updated readme --- README.md | 193 ++++++------------------------------------------ server/alexa.py | 6 +- 2 files changed, 29 insertions(+), 170 deletions(-) diff --git a/README.md b/README.md index 0642fc7..c38a58a 100644 --- a/README.md +++ b/README.md @@ -6,199 +6,54 @@ This is a custom component for Home Assistant, which allows you to synchronise y **This works even though they cut off third party access to the shopping lists in Summer 2024** -It is made of two main parts: +There are three parts: -- **The Server** - This is a small Selenium based application, which accesses your shopping list on the Amazon Website. -- **The Component** - This is the part you add to your Home Assistant installation. It connects to the server to periodically sync the shopping lists in both places +**The Server** +This is a small Selenium-based python application, which accesses your alexa shopping list via the Amazon Website. It can read what is on the list, add things to it and remove things from it. -## Step 1 - Installing the server +Selenium allows you to essentially remote control a web browser and can browse websites, read content, click buttons, etc. -The server runs as a headless background service. +The server runs on your home assistant device, or a different server on your network. -The server runs on TCP port 4000. This does NOT need to be accessible to the outside world, but does need to be accessible to your local network in some form. If you have very restrictive rules setup on your rig, you might need to open this up. But most should be fine. +**The Client** -Once the server is installed and running in some form, you are ready to move onto the next step. +In theory, you should rarely need to use the client. You need it to get the server set up. The client is like the remote control for the server. -There are a few different ways to install the server: +The client runs on your desktop computer or laptop, so you can talk to the server more easily. -### Pre-built container +**The Custom Component** -You can find pre-built containers on docker hub here: +This is the part you add to your Home Assistant installation. It talks with the server and the two work together to make sure your shopping lists on both HA and Alexa are kept in sync. -https://hub.docker.com/r/madmachinations/ha-alexa-shopping-list-sync -**When you run the container, make sure you mount a local directory into the container's `/config` path. This is where configuration and session data will be persisted.** +## Installation steps -These have been built for x86_64 and arm64 environments, so should run fine on most rigs. +You can find the installation guide on the wiki here: -However I'm not sure about older raspberry pi's and such. +https://github.com/madmachinations/home-assistant-alexa-shopping-list/wiki/Installation -The container generally doesn't use much system resources, it peaks when it's using the sync, as this is when the headless browser is being loaded and used. But when it is not synchronising, it just idles waiting for a signal to do something. +## Setting up a development environment -### Hass Add-on +You can find the development environment setup guide on the wiki here: -There is a HASS OS Add-on of the server. +https://github.com/madmachinations/home-assistant-alexa-shopping-list/wiki/Development-environment -Add this repository to your installation, and install the alexa shopping list add on: +## Troubleshooting and help -`https://github.com/madmachinations/home-assistant-alexa-shopping-list-hass` +If you get stuck or hit a problem, please read the troubleshooting steps first: -### Build your own container image +https://github.com/madmachinations/home-assistant-alexa-shopping-list/wiki/Troubleshooting-and-help -1) Download this repository -2) `cd` into the `server` directory -3) Run your `docker build ...` command -When you run the container, make sure you mount a local directory into the container's `/config` path. This is where configuration and session data will be persisted. +## Help out -### Non-containerised with systemd +I would appreciate any help from anyone for testing and further development on various fixes and improvements. -You can run the server manually as a service within systemd. +If you are not technical, there are other ways to help. Such as identifying duplicate issues, or helping other people in the community support discussion board here: -First, download this repository and mv the `server` directory to wherever you want it to be installed within your file system. +https://github.com/madmachinations/home-assistant-alexa-shopping-list/discussions/categories/community-support -Next, your system needs to have the following packages installed: - -- chromium -- chromium-chromedriver -- python3 -- pip3 - -Now let's install the python packages that are required: - -- `cd /wherever/you/installed/the/server/` -- `sudo pip3 install -r requirements.txt` - -Next, we need to setup a systemd service file: - -To do this, create a new file called `alexa-shopping-list.service` within your `/etc/systemd/service/` directory, which contains the following: - -``` -[Unit] -Description=Alexa Shopping List -After=network.target - -[Service] -ExecStart=/usr/bin/python3 /path/to/server/server.py - -# If the script crashes, restart it automatically -Restart=always -RestartSec=5 - -[Install] -WantedBy=multi-user.target -``` - -After this file is saved, now run these commands: - -- `sudo systemctl daemon-reload` -- `sudo systemctl enable alexa-shopping-list` -- `sudo systemctl start alexa-shopping-list` - -You can check if it is running with `sudo systemctl status alexa-shopping-list` - -## Step 2 - Configure the server - -Before the server can do anything, it needs to be configured. - -You can do this with the client script in this repository. - -So, if you have not done so already, download this repository first. - -You can download each version of the project files on the releases page here: - -https://github.com/madmachinations/home-assistant-alexa-shopping-list/releases - -You probably want whatever the latest one is. - -**THE CLIENT SCRIPT IS RUN ON THE COMPUTER YOU ARE USING RIGHT NOW, NOT ON YOUR HOME ASSISTANT BOX AND NOT WITHIN THE RUNNING CONTAINER. YOU NEED TO DOWNLOAD THE FILES FROM THIS REPOSITORY TO YOUR COMPUTER, AND THE CLIENT SCRIPT IS INSIDE THE CLIENT FOLDER** - -Before we begin, you need to make sure your system has both `python3` and `pip3` installed. - -If that is the case, `cd` into the `client` directory - -If this is the first time using the client, install it's dependencies with something like: - -`pip3 install --user -r requirements.txt` - -Now we are ready to run the client and configure our server. - -The client is opened like this: - -`python3 client.py ` - -So, let's assume the system you have installed the server onto has the IP address `192.168.0.200`; You would start the client like this: - -`python3 client.py 192.168.0.200` - -When the client starts it immediately tries to connect to the server. If it can connect, it checks to see if the server is configured. - -If the server is _not_ yet configured, the configuration process will start: - -1) The first thing it will ask, is what domain name do you access the amazon website through. The default value is `amazon.co.uk`, because I'm British, so... it is what it is. This has only been tested on amazon.co.uk so far. -2) Next it will check if the server is logged into your account on the amazon website, which it won't be. So it will immediately ask you to enter the email address and password you login to Amazon with. -3) If your account has MFA enabled, after a few moments it should ask you to enter your MFA code. -4) Assuming all of this went to plan, the server should now be authenticated with your account on the Amazon website. -5) You will now find yourself on the client command line, you can just type `quit` and press enter to close it, or press `ctrl + c`. If you have things on your alexa shopping list already, you can check if you can see them by typing `list` and pressing enter. After 5-10 seconds you should see your shopping list in the terminal. - -As far as Amazon is concerned, this is like you opening the website in chromium and using your account to use the shopping list. - -Your actual login credentials, your email and password, are NOT stored anywhere. They are used to perform the login, and they are forgotten immediately after this. - -Instead, all the cookies and values in the web browser session once logged in are saved by the server, and reloaded each time it has to do something. - -If it is synchronising regularly, this session should just stay alive. - -You should also be able to see it on your Amazon account as a place you are logged in. - -I will list all the client commands in a different section below. - - -## Step 3 - Install the custom component - -Now we're ready to add the custom component to Home Assistant. - -This component connects to the server and uses it to keep your HA shopping list synchronised. - -1) In your HA config directory, make sure there is a folder called `custom_components`. Create it if it does not exist. -2) Copy the `alexa_shopping_list` folder out of _this_ repository's `custom_components` folder and paste it into _your HA's_ `custom_components` folder. -3) Restart Home Assistant and wait for it to reload -4) In HA, go to Settings > Devices & Integrations and press Add integration. Find `Alexa Shopping List` and click on that to start the configuration process -5) The first config screen will ask you to enter the IP address and port number of the server we installed earlier. Enter your IP address, and the default port is 4000. Press next and the component will check if it can connect. -6) Once a successful connection is established to the server, it will ask you how frequently you want to synchronise the shopping list in minutes. I am running mine every 60 minutes. There is also a server which you can call at any time to force it to synchronise now. Choose a figure that is reasonable, don't spam it. -7) That's it! After a few moments, your HA shopping list should be replaced with whatever is on your alexa shopping list. - - -## Using the shopping list - -This component expects you primarily access your shopping list via Home Assistant directly. - -Each time it sychronises, it adds everything to your HA list which exists on your alexa list but not on your HA list. - -If an item is ticked-off as "completed" on your HA list, it will be removed from your Alexa list. - -If you added anything manually to your HA list, it will be added to your alexa list. - -Generally I add most things to my alexa list via an echo device and voice commands, and then I just want to read the shopping list in my HA app when I'm actually going shopping. - -## Client commands - -| Command | Description | Example | -| --- | --- | --- | -| `quit` or `exit` | Close the client | N/A | -| `list` | Lists all items on your Alexa list | N/A | -| `add {item}` | Adds an item to your Alexa list | `add cake` | -| `update {old} {new}` | Updates an item on you Alexa list | `update cake "baked beans"` | - `remove {item}` | Removes an item from your Alexa list | `remove "baked beans"` | - - -## Help and feedback - -I would also appreciate any help from anyone for testing and further development on various fixes and improvements. - -It was a fight to get the damn thing to work reliably, and I don't doubt it will require maintenance in the future. - -If you like this thing and it works for you, and you have the means, then please consider buying me a coffee. Which if I'm honest I will definitely spend on beer and pizza. But sure let's call that "coffee". +If you like this thing and you have the means, then please consider buying me a coffee. Which if I'm honest I will definitely spend on beer and pizza. But sure let's call that "coffee". Buy Me A Coffee diff --git a/server/alexa.py b/server/alexa.py index dc305b5..8bb954c 100644 --- a/server/alexa.py +++ b/server/alexa.py @@ -31,6 +31,9 @@ def __del__(self): def _get_file_location(self): return os.path.dirname(os.path.realpath(__file__)) + def _is_debug_mode(self): + return os.environ.get("ALEXA_SHOPPING_LIST_DEBUG", "0") == "1" + # ============================================================ # Selenium @@ -39,7 +42,8 @@ def _setup_driver(self): user_agent = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/128.0.0.0 Safari/537.36" chrome_options = Options() - chrome_options.add_argument("--headless") + if(self._is_debug_mode() == False): + chrome_options.add_argument("--headless") chrome_options.add_argument("window-size=1366,768") chrome_options.add_argument("--disable-gpu") chrome_options.add_argument("--no-sandbox")