From 50aa913c602e866253791d4dd2b81d46dba0f363 Mon Sep 17 00:00:00 2001 From: gabriel Date: Thu, 24 Oct 2024 14:48:24 +0200 Subject: [PATCH 1/2] Improved supported_types.md --- docs/drawcustom/supported_types.md | 446 ++++++++++++++--------------- 1 file changed, 210 insertions(+), 236 deletions(-) diff --git a/docs/drawcustom/supported_types.md b/docs/drawcustom/supported_types.md index 9d781a4..032946e 100644 --- a/docs/drawcustom/supported_types.md +++ b/docs/drawcustom/supported_types.md @@ -2,7 +2,7 @@ With `drawcustom`, you can create an image in Home Assistant and send the rendered image to an OpenEpaperLink AP. -The basic service call, looks like this: +## Basic Usage ```yaml service: open_epaper_link.drawcustom @@ -28,38 +28,18 @@ data: color: red ``` -## Data -### payload -Payload to draw, see below Types. - -Required: true - - -### backgroundcolor -Background color: black, white, red - -Required: true - - -### rotate -Rotate the whole image by 0, 90, 180, 270. - -Required: false (default: 0) - - -### dry-run -Generate image, but don't send it to the AP. - -Required: false (default: false) -```yaml -dry-run: true -``` +## Global Parameters +| Parameter | Description | Required | Default | Values | +|--------------|--------------------------------------|----------|---------|-------------------------| +| `payload` | Payload to draw, see below | Yes | - | | +| `background` | Background color of the entire image | Yes | - | `white`, `black`, `red` | +| `rotate` | Rotation of the entire image | No | `0` | `0`, `90`, `180`, `270` | +| `dry-run` | Generate image without sending to AP | No | `false` | `true`, `false` | ## Types ### text - Draws text. ```yaml @@ -72,59 +52,53 @@ Draws text. color: red ``` -#### Parameters - -- **value** (required) the text to display -- **x** (required) position on x axis -- **size** (optional) size of text, default: 20 -- **font** (optional) name of ttf file from `custom_components` folder. default: `ppb.ttf`. An additional font is available called `rbm.ttf`. If you want custom fonts, don't place them in the `custom_components` folder. Place them in, for example, `/media`, to not have them deleted by the next update. -- **color** (optional) font color of text. default: black -- **y** (optional) position on y axis -- **y_padding** (optional) offset to last text or multiline y position. works only if y is not provided. default: 10 -- **anchor** (optional) Position from the text, which shall be used as anchor. default: `lt` (left_top) for single lines, `la` (left_ascending) for mulitple lines. Other options include `mm` (middle_middle). See https://pillow.readthedocs.io/en/stable/handbook/text-anchors.html -- **max_width** (optional) creates line breaks in the provided text, if text is longer than `max_width` defines -- **spacing** (optional) if line breaks created in the provided text using `max_width`, set spacing between single lines. Default: 5 -- **stroke_width** (optional) adds stroke around text with color `stroke_fill`. Default: 0 -- **stroke_fill** (optional) the color of the added stroke. Default: white -- **align** (optional) left, center, right default: left (this sets the alignment of any **new lines**) -- **visible** (optional) show element, default: True - -### multiline - -This payload takes a string and a delimiter, and will break the string on every delimiter and move the cursor the amount `offset_y` down the canvas. +| Parameter | Description | Required | Default | Notes | +|----------------|--------------------------------------|----------|--------------------------------|-------------------------------------------------------------------------------------------| +| `value` | Text to display | Yes | - | String | +| `x` | X position | Yes | - | Pixels from left | +| `y` | Y position | No | Last text position + y_padding | Pixels from top | +| `size` | Font size | No | `20` | Pixels | +| `font` | Font file name | No | `ppb.ttf` | Available fonts: `ppb.ttf`, `rbm.ttf`, or custom | +| `color` | Text color | No | `black` | `black`, `white`, `red` | +| `anchor` | Text anchor point | No | `lt` (left-top) | [Pillow text anchors](https://pillow.readthedocs.io/en/stable/handbook/text-anchors.html) | +| `max_width` | Maximum text width before wrapping | No | - | Pixels | +| `spacing` | Line spacing for wrapped text | No | `5` | Pixels | +| `stroke_width` | Outline width | No | `0` | Pixels | +| `stroke_fill` | Outline color | No | `white` | `white`, `black`, `red` | +| `align` | Text alignment | No | `left` | `left`, `center`, `right` | +| `y_padding` | Vertical offset when y not specified | No | `10` | Pixels | +| `visible` | Show/hide element | No | `true` | `true`, `false` | + +### Multiline Text +Splits text into multiple lines based on a delimiter. ```yaml - type: multiline - value: "adb|asd" + value: "Line 1|Line 2|Line 3" delimiter: "|" font: "ppb.ttf" - offset_y: 50 x: 0 + offset_y: 50 size: 40 color: black - y_padding: 10 ``` -#### Parameters: - -- **value** (required) the text to display -- **delimiter** (required) the delimiting character, to split value, e.g. `#` -- **x** (required) position on x axis -- **offset_y** (required) This is the line height: how much space to start the next line down the y axis. -- **start_y** (optional) position on y axis -- **y_padding** (optional) offset to last text or multiline y position. works only if `start_y` is not provided. default: 10 -- **size** (optional) size of text, default: 20 -- **font** (optional) name of ttf font file (see [text](#text) above for details). default: `ppb.ttf` -- **color** (optional) font color of text. default: black -- **spacing** (optional) if multiline text, spacing between single lines -- **stroke_width** (optional) adds stroke around text with color `stroke_fill`. Default: 0 -- **stroke_fill** (optional) the color of the added stroke. Default: white -- **align** (optional) left, center, right default: left (if text contains `\n` this sets the alignment of the lines) -- **visible** (optional) show element, default: True - -### line - -Draws a line. +| Parameter | Description | Required | Default | Notes | +|-------------|--------------------------------|----------|---------------------------|---------------------------------------| +| `value` | Text with delimiters | Yes | - | String | +| `delimiter` | Character to split text | Yes | - | Single character | +| `x` | X position | Yes | - | Pixels from left | +| `offset_y` | Vertical spacing between lines | Yes | - | Pixels | +| `start_y` | Starting Y position | No | Last position + y_padding | Pixels from top | +| `size` | Font size | No | `20` | Pixels | +| `font` | Font file name | No | `ppb.ttf` | Available fonts: `ppb.ttf`, `rbm.ttf` | +| `color` | Text color | No | `black` | `black`, `white`, `red` | +| `spacing` | Additional line spacing | No | `0` | Pixels | +| `align` | Text alignment | No | `left` | `left`, `center`, `right` | +| `visible` | Show/hide element | No | `true` | `true`, `false` | + +### Line +Draws a straight line. ```yaml - type: line @@ -136,20 +110,19 @@ Draws a line. fill: red ``` -#### Parameters: - -- **x_start** (required) -- **y_start** (optional) if `y_start` is not provided, it will automatically try to add the line at the bottom of the last text block -- **y_padding** (optional) if no `y_start` is provided, this will offset the start of the line to the last text block -- **x_end** (required) -- **y_end** (optional) -- **fill** (optional) default black -- **width** (optional) default 1 -- **visible** (optional) show element, default: True - -### rectangle +| Parameter | Description | Required | Default | Notes | +|-------------|--------------------------------------|----------|-----------------|-------------------------| +| `x_start` | Starting X position | Yes | - | Pixels | +| `x_end` | Ending X position | Yes | - | Pixels | +| `y_start` | Starting Y position | No | Auto-positioned | Pixels | +| `y_end` | Ending Y position | No | `y_start` | Pixels | +| `fill` | Line color | No | `black` | `black`, `white`, `red` | +| `width` | Line thickness | No | `1` | Pixels | +| `y_padding` | Vertical offset when auto-positioned | No | `0` | Pixels | +| `visible` | Show/hide element | No | `true` | `true`, `false` | -Draws a rectangle. +### Rectangle +Draws a rectangle with optional rounded corners. ```yaml - type: rectangle @@ -162,22 +135,21 @@ Draws a rectangle. outline: black ``` -#### Parameters: - -- **x_start** (required) -- **y_start** (required) -- **x_end** (required) -- **y_end** (required) -- **fill** (optional) default `null`, use `null` to not draw the inside -- **outline** (optional) default black -- **width** (optional) width of outline, default 1 -- **visible** (optional) show element, default: True -- **radius** (optional) default 0, if set, the rectangle will be drawn with rounded corners -- **corners** (optional) if set, the rectangle will be drawn with rounded corners, possible values are `all`, or `top_left`, `top_right`, `bottom_left`, `bottom_right` separated by a comma, if set without radius the default radius will be 10 - -### rectangle pattern - -Draws rectangles that are repeated in x and y direction. +| Parameter | Description | Required | Default | Notes | +|-----------|------------------------|----------|---------|------------------------------------------------------------------------------------------| +| `x_start` | Left position | Yes | - | Pixels | +| `x_end` | Right position | Yes | - | Pixels | +| `y_start` | Top position | Yes | - | Pixels | +| `y_end` | Bottom position | Yes | - | Pixels | +| `fill` | Fill color | No | `null` | `black`, `white`, `red`, `null` | +| `outline` | Border color | No | `black` | `black`, `white`, `red` | +| `width` | Border thickness | No | `1` | Pixels | +| `radius` | Corner radius | No | `0` | Pixels | +| `corners` | Which corners to round | No | `all` | `all` or comma-separated list of: `top_left`, `top_right`, `bottom_left`, `bottom_right` | +| `visible` | Show/hide element | No | `true` | `true`, `false` | + +### Rectangle Pattern +Draws repeated rectangles in a grid pattern. ```yaml - type: rectangle_pattern @@ -194,25 +166,22 @@ Draws rectangles that are repeated in x and y direction. y_repeat: 4 ``` -#### Parameters: - -- **x_start** (required) -- **x_size** (required) length of rectangle in the x direction -- **x_offset** (required) distance between rectangles in x direction -- **y_start** (required) -- **y_size** (required) length of rectangle in the y direction -- **y_offset** (required) distance between rectangles in y direction -- **fill** (optional) default `null` use `null` to not draw the inside -- **outline** (optional) default black -- **width** (optional) default 1 -- **x_repeat** (required) number of rectangles in x direction -- **y_repeat** (required) number of rectangles in y direction -- **visible** (optional) show element, default: True -- **radius** (optional) default 0, if set, the rectangle will be drawn with rounded corners, if set without corners all corners will be rounded -- **corners** (optional) if set, the rectangle will be drawn with rounded corners, possible values are `all`, or `top_left`, `top_right`, `bottom_left`, `bottom_right` separated by a comma, if set without radius the default radius will be 10 - -### circle - +| Parameter | Description | Required | Default | Notes | +|------------|------------------------------|----------|---------|---------------------------------| +| `x_start` | Starting X position | Yes | - | Pixels | +| `x_size` | Width of each rectangle | Yes | - | Pixels | +| `x_offset` | Horizontal spacing | Yes | - | Pixels | +| `y_start` | Starting Y position | Yes | - | Pixels | +| `y_size` | Height of each rectangle | Yes | - | Pixels | +| `y_offset` | Vertical spacing | Yes | - | Pixels | +| `x_repeat` | Number of horizontal repeats | Yes | - | Integer | +| `y_repeat` | Number of vertical repeats | Yes | - | Integer | +| `fill` | Fill color | No | `null` | `black`, `white`, `red`, `null` | +| `outline` | Border color | No | `black` | `black`, `white`, `red` | +| `width` | Border thickness | No | `1` | Pixels | +| `visible` | Show/hide element | No | `true` | `true`, `false` | + +### Circle Draws a circle around a center point. ```yaml @@ -222,17 +191,17 @@ Draws a circle around a center point. radius: 20 ``` -#### Parameters: - -- **x** (required) x position of the center -- **y** (required) y position of the center -- **radius** (required) radius of the circle -- **fill** (optional) default `null`, use `null` to not draw the inside -- **outline** (optional) default black -- **width** (optional) width of outline, default 1 - -### ellipse - +| Parameter | Description | Required | Default | Notes | +|-----------|-------------------|----------|---------|---------------------------------| +| `x` | Center X position | Yes | - | Pixels | +| `y` | Center Y position | Yes | - | Pixels | +| `radius` | Circle radius | Yes | - | Pixels | +| `fill` | Fill color | No | `null` | `black`, `white`, `red`, `null` | +| `outline` | Border color | No | `black` | `black`, `white`, `red` | +| `width` | Border thickness | No | `1` | Pixels | +| `visible` | Show/hide element | No | `true` | `true`, `false` | + +### Ellipse Draws an ellipse inside the bounding box. ```yaml @@ -243,42 +212,43 @@ Draws an ellipse inside the bounding box. y_end: 100 ``` -#### Parameters: +| Parameter | Description | Required | Default | Notes | +|-----------|-------------------|----------|---------|---------------------------------| +| `x_start` | Left position | Yes | - | Pixels | +| `x_end` | Right position | Yes | - | Pixels | +| `y_start` | Top position | Yes | - | Pixels | +| `y_end` | Bottom position | Yes | - | Pixels | +| `fill` | Fill color | No | `null` | `black`, `white`, `red`, `null` | +| `outline` | Border color | No | `black` | `black`, `white`, `red` | +| `width` | Border thickness | No | `1` | Pixels | +| `visible` | Show/hide element | No | `true` | `true`, `false` | -- **x_start** (required) x position of the upper left corner -- **y_start** (required) y position of the upper left corner -- **x_end** (required) x position of the lower right corner -- **y_end** (required) y position of the lower right corner -- **fill** (optional) default `null`, use `null` to not draw the inside -- **outline** (optional) default black -- **width** (optional) width of outline, default 1 - -### icon - -Draws an icon. +### Icon +Draws Material Design Icons. ```yaml - type: icon - value: account-cowboy-hat + value: "account-cowboy-hat" x: 60 y: 120 size: 120 color: red ``` -#### Parameters: - -- value (required) name of icon from , may be optionally prefixed with "mdi:" -- x (required) x position -- y (required) y position -- size (required) e.g. 20 -- fill (optional) default black (was color before) -- anchor (optional) position from the text, (see [text](#text) above for details) -- **visible** (optional) show element, default: True +| Parameter | Description | Required | Default | Notes | +|-----------|-------------------|----------|---------|----------------------------------------------------------------------| +| `value` | Icon name | Yes | - | From [Material Design Icons](https://pictogrammers.com/library/mdi/) | +| `x` | X position | Yes | - | Pixels | +| `y` | Y position | Yes | - | Pixels | +| `size` | Icon size | Yes | - | Pixels | +| `fill` | Icon color | No | `black` | `black`, `white`, `red` | +| `anchor` | Icon anchor point | No | `la` | See text anchors | +| `visible` | Show/hide element | No | `true` | `true`, `false` | -### dlimg +Note: Icon name can be prefixed with `mdi:` (e.g., `mdi:account-cowboy-hat`) -Downloads an image from a URL and renders it. +### Download Image +Downloads and displays an image from a URL. ```yaml - type: dlimg @@ -290,17 +260,23 @@ Downloads an image from a URL and renders it. rotate: 0 ``` -#### Parameters: +| Parameter | Description | Required | Default | Notes | +|-----------|-------------------|----------|---------|-----------------------------------------| +| `url` | Image URL or path | Yes | - | HTTP/HTTPS URL, Data URI, or local path | +| `x` | X position | Yes | - | Pixels | +| `y` | Y position | Yes | - | Pixels | +| `xsize` | Target width | Yes | - | Pixels | +| `ysize` | Target height | Yes | - | Pixels | +| `rotate` | Rotation angle | No | `0` | Degrees | +| `visible` | Show/hide element | No | `true` | `true`, `false` | -- **url** (required) url of the image to download. Either the full http/https URL address for an externally accessible image or Data URI like 'data:image/gif;base64,R0lGODdhAQABAPAAAP8AAAAAACwAAAAAAQABAAACAkQBADs' or locally stored image needs to be e.g. `url: /config/media/chuck-icon.jpg` if stored within a folder called `media` in your main config or homeassistant folder. -- **x** (required) e.g. 20 -- **y** (required) e.g. 10 -- **xsize** (required) e.g. x size the image is resized -- **ysize** (required) e.g. y size the image is resized -- **rotate** (optional) default 0 -- **visible** (optional) show element, default: True +Notes: +- Local images must be in `/config/media/` +- Data URIs supported (e.g., `data:image/gif;base64,...`) +- External images must be publicly accessible -### qrcode +### QR Code +Generates and displays a QR code. ```yaml - type: qrcode @@ -313,77 +289,75 @@ Downloads an image from a URL and renders it. bgcolor: "white" ``` -#### Parameters: - -- **data** (required) content of the qr code -- **x** (required) e.g. 20 -- **y** (required) e.g. 10 -- **boxsize** (optional) default 2 -- **border** (optional) default 1 -- **color** (optional) default black -- **bgcolor** (optional) default white -- **visible** (optional) show element, default: True - -### plot +| Parameter | Description | Required | Default | Notes | +|-----------|----------------------|----------|---------|-------------------------| +| `data` | Content to encode | Yes | - | String | +| `x` | X position | Yes | - | Pixels | +| `y` | Y position | Yes | - | Pixels | +| `boxsize` | Size of each QR box | No | `2` | Pixels | +| `border` | QR code border width | No | `1` | Units | +| `color` | QR code color | No | `black` | `black`, `white`, `red` | +| `bgcolor` | Background color | No | `white` | `black`, `white`, `red` | +| `visible` | Show/hide element | No | `true` | `true`, `false` | -Renders the history of given home assistant entities as a line plot. -The plot will scale according to the data, so you should only use multiple entities within the same data range. +### Plot +Renders historical data from Home Assistant entities as a line plot. ```yaml - type: plot x_start: 10 y_start: 20 - x_end: 199 # inclusive - y_end: 119 # inclusive - duration: 36000 # 10h in seconds - low: 10 # if all values are larger than 10, we include 10 anyway - high: 20 # if all values are smaller than 20, we include 20 anyway - ylegend: - position: right # show legend on the right - color: red - yaxis: - tick_width: 4 # show very wide ticks - grid: 3 # place a grid point every 3rd pixel + x_end: 199 + y_end: 119 + duration: 36000 + low: 10 + high: 20 data: - - entity: sensor.my_room_temperature - width: 3 # show very thick line - - entity: sensor.my_outside_temperature + - entity: sensor.temperature + width: 3 + - entity: sensor.humidity color: red + ``` + +| Parameter | Description | Required | Default | Notes | +|------------|--------------------------|----------|---------------|-----------------| +| `x_start` | Left position | No | `0` | Pixels | +| `y_start` | Top position | No | `0` | Pixels | +| `x_end` | Right position | No | Canvas width | Pixels | +| `y_end` | Bottom position | No | Canvas height | Pixels | +| `duration` | Time range | No | `86400` | Seconds | +| `low` | Minimum Y value | No | Auto | Number | +| `high` | Maximum Y value | No | Auto | Number | +| `font` | Font file | No | `ppb.ttf` | Font name | +| `size` | Font size | No | `10` | Pixels | +| `debug` | Show debug borders | No | `false` | `true`, `false` | +| `data` | List of entities to plot | Yes | - | Array | +| `visible` | Show/hide element | No | `true` | `true`, `false` | + +#### Plot Legend Options +```yaml +ylegend: + width: -1 # Auto width if -1 + color: black # Legend color + position: left # left or right + font: ppb.ttf # Legend font + size: 10 # Legend font size ``` -#### Parameters: - -- **x_start** (optional, default `0`) the left start of the whole plot (inlusive) -- **y_start** (optional, default `0`) the top start of the whole plot (inlusive) -- **x_end** (optional, default `0`) the right end of the whole plot (inlusive) -- **y_end** (optional, default `0`) the bottom end of the whole plot (inlusive) -- **duration** (optional, default `86400`) the number of seconds to look back, defaults to one day, please keep in mind tat the recorder might not have the most up to date data -- **font** (optional, default `ppb.ttf`) the font used for text output (may be overwritten by more specific font statements) -- **size** (optional, default `10`) the respective font size -- **low** (optional) if provided, it is ensured that the given value is included on the lower end of the plot (e.g., if values are in the range 12 to 17, providing 10 will make 10 the lower end, providing 14 changes nothing) -- **high** (optional) if provided, it is ensured that the given value is included on the upper end of the plot -- **debug** (optional, default `false`) if `true`, draw a black rectangle around the whole plot region and a red rectangle around the region with the data -- **ylegend** (optional) displays the highest and lowest value as a legend on the side, set to `null` to disable - - **width** (optional, default `-1`) the number of pixels reserved for the legend, if `-1` it is automatically computed - - **color** (optional, default `black`) the color for the legend - - **position** (optional, default `left`) either `left` or `right`, the position of the legend - - **font** / **size** (optional) the font file and size, defaults to the font selected at main level -- **yaxis** (optional) displays a vertical axis with ticks and a grid, set to `null` to disable - - **width** (optional, default `1`) the width of the vertical axis - - **color** (optional, default `black`) the color of the vertical axis - - **tick_width** (optional, default `2`) the width for each axis tick, set to `0` to disable - - **tick_every** (optional, default `1.0`) place a tick at every - - **grid** (optional, default `5`) place a point horizontally every `grid`th pixel at the coordinates of the ticks, set to `null` to disable - - **grid_color** (optional, default `black`) color for the grid points -- **data** (required) a list of objects for which the history should be rendered, each object has the following properties: - - **entity** (required) the home assistant entity with has numeric data - - **color** (optional, default `black`) the color of the plot - - **width** (optional, default `1`) the width of the plot line - - **joint** (optional, default `null`) sets the `joint` option for the [line draw funtion](https://pillow.readthedocs.io/en/stable/reference/ImageDraw.html#PIL.ImageDraw.ImageDraw.line), can be `curve` or `null` -- **visible** (optional) show element, default: True +#### Plot Axis Options +```yaml +yaxis: + width: 1 # Axis line width + color: black # Axis color + tick_width: 2 # Width of tick marks + tick_every: 1.0 # Tick interval + grid: 5 # Grid point spacing + grid_color: black # Grid color +``` ### Progress Bar -Draws a progress bar +Displays a progress bar with optional percentage text. + ```yaml - type: progress_bar x_start: 10 @@ -398,17 +372,17 @@ Draws a progress bar show_percentage: true ``` -#### Parameters: - -- **x_start** (required) -- **y_start** (required) -- **x_end** (required) -- **y_end** (required) -- **progress** (required) progress in percent, eg. `42` -- **direction** (optional, default `right`) direction in which the progress bar should be filled, possible values are `right`, `left` `up`, `down` -- **background** (optional, default `white`) -- **fill** (optional, default `red`) color of the progress bar -- **outline** (optional, default `black`) color of outline -- **width** (optional, default `1`) width of outline -- **visible** (optional, default `True`) show element -- **show_percentage** (optional, default `False`) show percentage in the middle of the progress bar \ No newline at end of file +| Parameter | Description | Required | Default | Notes | +|-------------------|----------------------|----------|---------|-------------------------------| +| `x_start` | Left position | Yes | - | Pixels | +| `y_start` | Top position | Yes | - | Pixels | +| `x_end` | Right position | Yes | - | Pixels | +| `y_end` | Bottom position | Yes | - | Pixels | +| `progress` | Progress value | Yes | - | 0-100 | +| `direction` | Fill direction | No | `right` | `right`, `left`, `up`, `down` | +| `background` | Background color | No | `white` | `white`, `black`, `red` | +| `fill` | Progress bar color | No | `red` | `white`, `black`, `red` | +| `outline` | Border color | No | `black` | `white`, `black`, `red` | +| `width` | Border thickness | No | `1` | Pixels | +| `show_percentage` | Show percentage text | No | `false` | `true`, `false` | +| `visible` | Show/hide element | No | `true` | `true`, `false` | \ No newline at end of file From 713e67104bbf74813b6dabb0cfd9f4a042789504 Mon Sep 17 00:00:00 2001 From: gabriel Date: Thu, 24 Oct 2024 15:12:43 +0200 Subject: [PATCH 2/2] Improved README.md --- README.md | 229 +++++++++++++++++++++++++++++------------------------- 1 file changed, 124 insertions(+), 105 deletions(-) diff --git a/README.md b/README.md index 653bab0..87356e9 100644 --- a/README.md +++ b/README.md @@ -9,99 +9,147 @@ -Home Assistant Integration for the OpenEPaperLink project +Home Assistant Integration for the [OpenEPaperLink](https://github.com/jjwbruijn/OpenEPaperLink) project, enabling control and monitoring of electronic shelf labels (ESLs) through Home Assistant. + +## Features + +### 🔌 Entities and Devices +- Each tag and AP is exposed as a device in Home Assistant +- Sensor data for each tag: + - Temperature + - Battery voltage and percentage + - Signal strength (RSSI) + - Link Quality Index (LQI) + - Last seen timestamp + - Next update/checkin time + - Wakeup reason + - Device capabilities +- Sensor data for each AP: + - DBSize + - Free heap + - Free space + - IP address + - Recordcount + - Run state + - AP state + - Systime + - Temperature + - Wi-Fi RSSI + - Wi-Fi SSID + - Wi-Fi state + +### ⚙️ AP Configuration Options +- Alias +- Bluetooth +- IEEE 802.15.4 channel selection +- Language selection +- Lock tag inventory setting +- Maximum sleep duration settings +- No-updates time window configuration +- AP Image preview setting +- RGB LED brightness control +- TFT brightness control +- Time zone configuration +- Wi-Fi power settings + +### 🎨 Display Controls +Several services for controlling the display content: + +#### drawcustom (Recommended) +The most flexible and powerful service for creating custom displays. Supports: +- Text with multiple fonts and styles +- Shapes (rectangles, circles, lines) +- Icons from Material Design Icons +- QR codes +- Images from URLs +- Plots of Home Assistant sensor data +- Progress bars + +[View full drawcustom documentation →](docs/drawcustom/supported_types.md) + +#### Legacy Services (Deprecated) +- **dlimg**: Download and display images from URLs +- **lines5**: Display 5 lines of text (1.54" displays only) +- **lines4**: Display 4 lines of text (2.9" displays only) + +### 🚦 Device Management +Services for managing ESL devices: +- `clear_pending`: Clear pending updates +- `force_refresh`: Force display refresh +- `reboot_tag`: Reboot tag +- `scan_channels`: Initiate channel scan +- `reboot_ap`: Reboot the access point -Feature Request and code contributions are welcome! +## Installation -## Functionality +### Option 1: HACS Installation (Recommended) +1. Click on HACS in the Home Assistant menu +2. Click `Integrations` +3. Click the `EXPLORE & DOWNLOAD REPOSITORIES` button +4. Search for `OpenEPaperLink` +5. Click the `DOWNLOAD` button +6. Restart Home Assistant -### Sensors +### Option 2: Manual Installation +1. Download the `open_epaper_link` folder from the [latest release](https://github.com/jonasniesner/open_epaper_link_homeassistant/releases/latest) +2. Copy it to your [`custom_components` folder](https://developers.home-assistant.io/docs/creating_integration_file_structure/#where-home-assistant-looks-for-integrations) +3. Restart Home Assistant -Every sensor of the tags is exposed in Home Assistant. -Every tag and the AP is exposed as a device. +## Configuration -### Services +### Automatic Configuration +Add OpenEPaperLink to your Home Assistant instance using this button: -#### drawcustom -This Service call draws a image local in home assistant, and will send it to the EPaper AP afterwards. To not draw the inside of the rectangle use `null` as the `fill` color value. +[![Add Integration](https://user-images.githubusercontent.com/31328123/189550000-6095719b-ca38-4860-b817-926b19de1b32.png)](https://my.home-assistant.io/redirect/config_flow_start?domain=open_epaper_link) -Example Call: -``` +### Manual Configuration +1. Browse to your Home Assistant instance +2. Go to Settings → Devices & Services +3. Click the `Add Integration` button in the bottom right +4. Search for and select "OpenEPaperLink" +5. Follow the on-screen instructions + +## Usage Examples + +### Basic Custom Display +```yaml service: open_epaper_link.drawcustom target: - entity_id: - - open_epaper_link.0000021EC9EC743A + entity_id: open_epaper_link.0000021EC9EC743A data: background: white - rotate: 270 - ttl: 300 + rotate: 0 payload: - - type: rectangle - outline: red - fill: white - width: 5 - x_start: 10 - y_start: 10 - x_end: 185 - y_end: 240 - - type: line - fill: red - width: 3 - x_start: 0 - y_start: 237 - x_end: 196 - y_end: 240 - type: text value: "Hello World!" font: "ppb.ttf" - x: 0 - "y": 0 + x: 10 + y: 10 size: 40 color: red - - type: icon - value: account-cowboy-hat - x: 60 - y: 120 - size: 120 - color: red ``` -Supported payload types, see [drawcustom payload types](docs/drawcustom/supported_types.md) - -#### Download Image (deprecated, use drawcustom for more options) - -Download an image from the provided url and if required, resized it for the esl it should be displayed on. - -This requires that the esl has checked in once before fo Home Assistant knows the hardware type of it so if this service fail, wait 10 to 20 minutes. - -#### 5 Line Display (deprecated, use drawcustom for more options) - -Displays 5 (or up to 10) lines of text on a small 1.54" esl. If a text line contains a newline (\n), it will be split in 2 lines. -Only works on 1.54" M2 displays. - -#### 4 Line Display (deprecated, use drawcustom for more options) - -Displays 4 (or up to 8) lines of text on a 2.9" esl. If a text line contains a newline, it will be split in 2 lines. -Only works on 2.9" M2 displays. - -#### Example Service Call -Go to Developer Tools, Services, select the OpenEPaperLink: 4 Line Display service and paste the below in to the YAML editor. Replace the sensor names in curly brackets with values from your own system. Note that floats work better when rounded and that all numbers work better when converted to strings. - -``` -service: open_epaper_link.lines4 +### Progress Bar with Icon +```yaml +service: open_epaper_link.drawcustom target: - entity_id: - - open_epaper_link.0000021EDE313B15 + entity_id: open_epaper_link.0000021EC9EC743A data: - line1: " Time: {{ states('sensor.time') | string }} " - line2: " LR Temp: {{ state_attr('climate.living_room_2','current_temperature') | string }} C " - line3: " Yest. Elec {{ state_attr('sensor.electricity_yesterday_previous_accumulative_consumption','total') | round(2) | string }} kWh " - line4: "Car: {{ states('sensor.car_state_of_charge') | int | string }} % / {{ ((states('sensor.id_3_pro_performance_range')) | float / 1.609344) | int | string }} miles {{ states('sensor.bins') }} " - border: r - format1: mbbw - format2: mrbw - format3: lbrw - format4: mwrb + background: white + payload: + - type: progress_bar + x_start: 10 + y_start: 10 + x_end: 180 + y_end: 30 + progress: 75 + fill: red + show_percentage: true + - type: icon + value: mdi:battery-70 + x: 190 + y: 20 + size: 24 ``` If a template with a numeric sensor value still does not work, try appending a non-numeric string (can't be a blank string or just a space) e.g. @@ -109,36 +157,7 @@ If a template with a numeric sensor value still does not work, try appending a n " {{ (states('sensor.car_range') | float / 1.609344 ) | int }} mi " ``` -## Installation - -### If you use [HACS](https://hacs.xyz/): - -1. Click on HACS in the Home Assistant menu -2. Click on `Integrations` -3. Click the `EXPLORE & DOWNLOAD REPOSITORIES` button -4. Search for `OpenEPaperLink` -5. Click the `DOWNLOAD` button -6. Restart Home Assistant - -### Manually: - -1. Copy `open_epaper_link` folder from [latest release](https://github.com/jonasniesner/open_epaper_link_homeassistant/releases/latest) to [`custom_components` folder](https://developers.home-assistant.io/docs/creating_integration_file_structure/#where-home-assistant-looks-for-integrations) in your config folder -2. Restart Home Assistant - -## Configuration - -Adding OpenEPaperLink to your Home Assistant instance can be done via the user interface, by using this My button: - -[![image](https://user-images.githubusercontent.com/31328123/189550000-6095719b-ca38-4860-b817-926b19de1b32.png)](https://my.home-assistant.io/redirect/config_flow_start?domain=open_epaper_link) - -### Manual configuration steps -If the above My button doesn’t work, you can also perform the following steps manually: - -1. Browse to your Home Assistant instance -2. In the sidebar click on Settings -3. From the configuration menu select: Devices & Services -4. In the bottom right, click on the `Add Integration` button -5. From the list, search and select “OpenEPaperLink” -6. Follow the instructions on screen to complete the setup - - +## Contributing +- Feature requests and bug reports are welcome! Please open an issue on GitHub +- Pull requests are encouraged +- Join the [Discord server](https://discord.com/invite/eRUHt4u5CZ) to discuss ideas and get help \ No newline at end of file