Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update Readme for GitHub Container Registry #12

Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions Dockerfile
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
FROM python:3.12-slim-bookworm
LABEL org.opencontainers.image.source=https://github.com/snicker/juicepassproxy

ENV MQTT_HOST="127.0.0.1"
ENV MQTT_PORT=1883
Expand Down
77 changes: 40 additions & 37 deletions README.MD
Original file line number Diff line number Diff line change
@@ -1,39 +1,36 @@
# Juicepass Proxy
# JuicePass Proxy

Builds upon some work by lovely folks in this issue:
This tool will publish JuiceBox data by using a Man in the Middle UDP proxy to MQTT that is auto-discoverable by HomeAssistant. The `Enel X Way` app will continue to function.

https://github.com/home-assistant/core/issues/86588
Builds upon work by lovely folks in this issue: https://github.com/home-assistant/core/issues/86588

This tool will publish Juicebox data from a UDP proxy to MQTT discoverable by HomeAssistant.

Hopefully we won't need this if EnelX fixes their API!
_Hopefully we won't need this if EnelX fixes their API!_

#### It is required that both your JuiceBox and the machine you are running `juicepassproxy` on have internal static IPs on your intranet.

## Docker Compose Installation

### Features
* If JuiceBox Local IP is defined, it will run a telnet script to get the EnelX Server and Port.

* If DST is not defined, it will use `dig` with the CloudFlare DNS (1.1.1.1) to get the IP address of the EnelX Server and avoid a DNS lookup loop.

* If SRC is not defined, it will use `ifconfig` to get the Local IP address of the Docker.

### Instructions

1. Configure your DNS server running on your network (like Pi-hole or your router) to route all UDP traffic from your JuiceBox to the machine running this proxy. Instructions for how to do this will vary by router. [See below](#getting-enelx-server-ips) for instructions on what EnelX Server you need to override.

1. Place the Dockerfile somewhere on your machine.
1. Configure your DNS server running on your network (like Pi-hole or your router) to route all UDP traffic from your JuiceBox to the machine running this proxy. Instructions for how to do this will vary by router. See [Getting EnelX Server IPs](#getting-enelx-server-ips) for instructions on what EnelX Server you need to override.

1. Add the `juicepassproxy` service to your Docker Compose file.

A. Set the `build:` line to point to the location of the Dockerfile.

B. Set `ports:` to the port listed in the UDCP line [below](#getting-enelx-server-ips).
A. Set `ports:` to the port listed in the UDCP line _(see [Getting EnelX Server IPs](#getting-enelx-server-ips))_.

1. Define the applicable environment variables ([*see below for details*](#docker-environment-variables)).
B. Define the applicable environment variables _(see [Docker Environment Variables](#docker-environment-variables))_.

1. Start the Docker container.

### Example Docker Compose

```yaml
version: '3.8'

Expand All @@ -46,7 +43,7 @@ networks:

services:
juicepassproxy:
build: ./juicepassproxy
image: ghcr.io/snicker/juicepassproxy:latest
hostname: juicepassproxy
container_name: juicepassproxy
restart: unless-stopped
Expand All @@ -56,10 +53,9 @@ services:
- 8047:8047/udp
environment:
- JUICEBOX_LOCAL_IP=10.100.50.30
- MQTT_HOST=10.100.200.5
- MQTT_USER=mosquitto
- MQTT_PASS=***
- MQTT_HOST=10.100.200.5
- DEBUG=true
volumes:
- /etc/localtime:/etc/localtime:ro
```
Expand All @@ -68,20 +64,23 @@ services:

Variable | Required | Description & Default |
-- | -- | --
JUICEBOX_LOCAL_IP | **Recommended** | If defined, it will attempt to get the EnelX Server and Port using Telnet. If unsuccessful, it will default to the EnelX Server and Port below.
SRC | No | If not defined, it will attempt to get the Local Docker IP. If unsuccessful, it will default to 127.0.0.1.
DST | No | If not defined, it will attempt to get the IP of the EnelX Server. If unsuccessful, it will default to 54.161.185.130. If manually defined, you should only use the IP address of the EnelX Server and not the fully qualified domain name to avoid DNS lookup loops.
ENELX_SERVER | No | juicenet-udp-prod3-usa.enelx.com
ENELX_PORT | No | 8047
MQTT_HOST | No | 127.0.0.1
MQTT_PORT | No | 1883
MQTT_USER | No |
MQTT_PASS | No |
MQTT_DISCOVERY_PREFIX | No | homeassistant
DEVICE_NAME | No | JuiceBox
DEBUG | No | false

## Manual Installation
**JUICEBOX_LOCAL_IP** | **Recommended** | If defined, it will attempt to get the EnelX Server and Port using Telnet. If unsuccessful, it will default to the EnelX Server and Port below.
**SRC** | No | If not defined, it will attempt to get the Local Docker IP. If unsuccessful, it will default to 127.0.0.1.
**DST** | No | If not defined, it will attempt to get the IP of the EnelX Server. If unsuccessful, it will default to 54.161.185.130. If manually defined, you should only use the IP address of the EnelX Server and not the fully qualified domain name to avoid DNS lookup loops.
**ENELX_SERVER** | No | juicenet-udp-prod3-usa.enelx.com
**ENELX_PORT** | No | 8047
**MQTT_HOST** | No | 127.0.0.1
**MQTT_PORT** | No | 1883
**MQTT_USER** | No |
**MQTT_PASS** | No |
**MQTT_DISCOVERY_PREFIX** | No | homeassistant
**DEVICE_NAME** | No | JuiceBox
**DEBUG** | No | false


<details>
<summary><h2>Manual Installation</h2></summary>

1. Clone this repository
2. Use Python 3.10+ (I recommend setting up a virtual environment)
3. Install requirements `pip install -r requirements.txt`
Expand All @@ -107,19 +106,23 @@ options:
--name DEVICE_NAME Home Assistant Device Name (default: Juicebox)
```

*For **DST**, you should only use the IP address of the EnelX Server and **not** the fully qualified domain name to avoid DNS lookup loops.*
_For **DST**, you should only use the IP address of the EnelX Server and **not** the fully qualified domain name (FQDN) to avoid DNS lookup loops._

</details>

## Getting EnelX Server IPs

To get the destination IP:Port of the EnelX server, telnet to your Juicenet device:
`$ telnet 192.168.x.x 2000`
and give a `list` command:
and type the `list` command:

```
> list
> ! # Type Info
> # 0 FILE webapp/index.html-1.4.0.24 (1995, 0)
> # 1 UDPC juicenet-udp-prod3-usa.enelx.com:8047 (26674)
list
! # Type Info
# 0 FILE webapp/index.html-1.4.0.24 (1995, 0)
# 1 UDPC juicenet-udp-prod3-usa.enelx.com:8047 (26674)
```

The address is in the `UDPC` line. Run, `ping`, `nslookup`, or similar command to determine the IP. Currently, `juicenet-udp-prod3-usa.enelx.com` is `54.161.185.130`.
The address is in the `UDPC` line. Run, `ping`, `nslookup`, or similar command to determine the IP.

As of November, 2023: `juicenet-udp-prod3-usa.enelx.com` = `54.161.185.130`.