From b822c4aef42fc88048047389d6ef36b7b463c2e4 Mon Sep 17 00:00:00 2001 From: Thomas Lauterbach Date: Fri, 14 Feb 2025 16:34:22 +0100 Subject: [PATCH] Fixes blinkText init and improves README Signed-off-by: Thomas Lauterbach --- .../README.md | 227 +++++++++++++++--- .../handler/AwtrixLightAppHandler.java | 6 +- 2 files changed, 197 insertions(+), 36 deletions(-) diff --git a/bundles/org.openhab.binding.mqtt.awtrixlight/README.md b/bundles/org.openhab.binding.mqtt.awtrixlight/README.md index b76f2de6c4b92..c6df40dcff5c4 100644 --- a/bundles/org.openhab.binding.mqtt.awtrixlight/README.md +++ b/bundles/org.openhab.binding.mqtt.awtrixlight/README.md @@ -80,38 +80,199 @@ The button events can be used by rules to change the displayed app or perform an | `temperature` | Number:Temperature | R | Device temperature: Temperature in °C as measured by the built-in temperature sensor. For the Ulanzi clock values are usually very inaccurate. | ### App Channels (`awtrixapp`) -| Channel | Type | Read/Write | Description | -|-----------------------|----------------------|------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `active` | Switch | W | Enable/disable the app: Switches the app on or off. Note that channels of inactive apps will be reset to their default values during a restart of openHAB. | -| `autoscale` | Switch | RW | Enable/disable autoscaling for bar and linechart. | -| `background` | Color | RW | Sets a background color. | -| `bar` | String | RW | Shows a bar chart: Send a string with values separated by commas (e.g. "value1,value2,value3"). Only the last 16 values will be displayed. | -| `blink` | Number:Time | RW | Blink text: Blink the text in the specified interval. Ignored if gradientColor or rainbow are set. | -| `center` | Switch | RW | Center short text horizontally and disable scrolling. | -| `color` | Color | RW | Text, bar or line chart color. | -| `duration` | Number:Time | RW | Display duration in seconds. | -| `effect` | String | RW | Display effect (see https://blueforcer.github.io/awtrix3/#/effects for possible values). | -| `effect-blend` | Switch | RW | Enable smoother effect transitions. Only to be used with effect. | -| `effect-palette` | String | RW | Color palette for effects (see https://blueforcer.github.io/awtrix3/#/effects for possible values and how to create custom palettes). Only to be used with effect. | -| `effect-speed` | Number:Dimensionless | RW | Effect animation speed: Higher means faster (see https://blueforcer.github.io/awtrix3/#/effects). Only to be used with effect. | -| `fade` | Number:Time | RW | Fade text: Fades the text in and out in the specified interval. Ignored if gradientColor or rainbow are set. | -| `gradient-color` | Color | RW | Secondary color for gradient effects. Use color for setting the primary color. | -| `icon` | String | RW | Icon name to display: Install icons on the clock device first. | -| `lifetime` | Number:Time | RW | App lifetime: Define how long the app will remain active on the clock. | -| `lifetime-mode` | String | RW | Lifetime mode: Define if the app should be deleted (Command DELETE) or marked as stale (Command STALE) after lifetime. | -| `line` | String | RW | Shows a line chart: Send a string with values separated by commas (e.g. "value1,value2,value3"). Only the last 16 values will be displayed. | -| `overlay` | String | RW | Enable overlay mode: Shows a weather overlay effect (can be any of clear, snow, rain, drizzle, storm, thunder, frost). | -| `progress` | Number:Dimensionless | RW | Progress value: Shows a progress bar at the bottom of the app with the specified percentage value. | -| `progress-background` | Color | RW | Progress bar background color: Background color for the progress bar. | -| `progress-color` | Color | RW | Progress bar color: Color for the progress bar. | -| `push-icon` | String | RW | Push icon animation (STATIC=Icon doesn't move, PUSHOUT=Icon moves with text and will not appear again, PUSHOUTRETURN=Icon moves with text but appears again when the text starts to scroll again). | -| `rainbow` | Switch | RW | Enable rainbow effect: Uses a rainbow effect for the displayed text. | -| `reset` | Switch | RW | Reset app to default state: All channels will be reset to their default values. | -| `scroll-speed` | Number:Dimensionless | RW | Text scrolling speed: Provide as percentage value. The original speed is 100%. Values above 100% will increase the scrolling speed, values below 100% will decrease it. Setting this value to 0 will disable scrolling completely. | -| `text` | String | RW | Text to display. | -| `text-case` | Number:Dimensionless | RW | Set text case (0=normal, 1=uppercase, 2=lowercase). | -| `text-offset` | Number:Dimensionless | RW | Text offset position: Horizontal offset of the text in pixels. | -| `top-text` | String | RW | Draws the text on the top of the display. | + +| Channel | Action parameter (see Actions) | Action parameter type | Type | Read/Write | Description | | +|-----------------------|------------------------------------------|------------------------------------------------|----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---| +| `active` | - | Switch | W | Enable/disable the app: Switches the app on or off. Note that channels of inactive apps will be reset to their default values during a restart of openHAB. | | | +| `autoscale` | `autoscale` | boolean | Switch | RW | Enable/disable autoscaling for bar and linechart. | | +| `background` | `background` | int[] (rgb-Array) | Color | RW | Sets a background color. | | +| `bar` | `bar` | String | String | RW | Shows a bar chart: Send a string with values separated by commas (e.g. "value1,value2,value3"). Only the last 16 values will be displayed. | | +| `blink` | `blinkText` | BigDecimal (in milliseconds) | Number:Time | RW | Blink text: Blink the text in the specified interval. Ignored if gradientColor or rainbow are set. | | +| `center` | `center` | boolean | Switch | RW | Center short text horizontally and disable scrolling. | | +| `color` | `color` | BigDecimal[] (rgb-Array) | Color | RW | Text, bar or line chart color. | | +| `duration` | `duration` | BigDecimal | Number:Time | RW | Display duration in seconds. | | +| `effect` | `effectSettings` | Map<String, Object> | String | RW | Display effect (see https://blueforcer.github.io/awtrix3/#/effects for possible values). | | +| `effect-blend` | `blend` as key in `effectSettings` | boolean | Switch | RW | Enable smoother effect transitions. Only to be used with effect. | | +| `effect-palette` | `palette` as key in `effectSettings` Map | String ("None" for default) | String | RW | Color palette for effects (see https://blueforcer.github.io/awtrix3/#/effects for possible values and how to create custom palettes). Only to be used with effect. | | +| `effect-speed` | `speed` as key in `effectSettings` Map | BigDecimal | Number:Dimensionless | RW | Effect animation speed: Higher means faster (see https://blueforcer.github.io/awtrix3/#/effects). Only to be used with effect. | | +| `fade` | `fadeText` | BigDecimal (in milliseconds) | Number:Time | RW | Fade text: Fades the text in and out in the specified interval. Ignored if gradientColor or rainbow are set. | | +| `gradient-color` | `gradient` | BigDecimal[] (rgb-Array) | Color | RW | Secondary color for gradient effects. Use color for setting the primary color. | | +| `icon` | `icon` | String | String | RW | Icon name to display: Install icons on the clock device first. | | +| `lifetime` | `lifetime` | BigDecimal | Number:Time | RW | App lifetime: Define how long the app will remain active on the clock. | | +| `lifetime-mode` | `lifetimeMode` | BigDecimal (0=DELETE, 1=STALE) | String | RW | Lifetime mode: Define if the app should be deleted (Command DELETE) or marked as stale (Command STALE) after lifetime. | | +| `line` | `line` | String | String | RW | Shows a line chart: Send a string with values separated by commas (e.g. "value1,value2,value3"). Only the last 16 values will be displayed. | | +| `overlay` | `overlay` | String | String | RW | Enable overlay mode: Shows a weather overlay effect (can be any of clear, snow, rain, drizzle, storm, thunder, frost). | | +| `progress` | `progress` | String | Number:Dimensionless | RW | Progress value: Shows a progress bar at the bottom of the app with the specified percentage value. | | +| `progress-background` | `progressBC` | BigDecimal[] (rgb-Array) | Color | RW | Progress bar background color: Background color for the progress bar. | | +| `progress-color` | `progressC` | BigDecimal[] (rgb-Array) | Color | RW | Progress bar color: Color for the progress bar. | | +| `push-icon` | `pushIcon` | BigDecimal (0=STATIC, 1=PUSHOUT, 2=PUSHRETURN) | String | RW | Push icon animation (STATIC=Icon doesn't move, PUSHOUT=Icon moves with text and will not appear again, PUSHOUTRETURN=Icon moves with text but appears again when the text starts to scroll again). | | +| `rainbow` | `rainbow` | boolean | Switch | RW | Enable rainbow effect: Uses a rainbow effect for the displayed text. | | +| `reset` | - | | Switch | RW | Reset app to default state: All channels will be reset to their default values. | | +| `scroll-speed` | `scrollSpeed` | BigDecimal | Number:Dimensionless | RW | Text scrolling speed: Provide as percentage value. The original speed is 100%. Values above 100% will increase the scrolling speed, values below 100% will decrease it. Setting this value to 0 will disable scrolling completely. | | +| `text` | `text` | String | String | RW | Text to display. | | +| `text-case` | `textCase` | BigDecimal | Number:Dimensionless | RW | Set text case (0=normal, 1=uppercase, 2=lowercase). | | +| `text-offset` | `textOffset` | BigDecimal | Number:Dimensionless | RW | Text offset position: Horizontal offset of the text in pixels. | | +| `top-text` | `topText` | boolean | Switch | RW | Draws the text on the top of the display. | | + +## Actions + +The binding supports various actions that can be used in rules to control the Awtrix display. To use these actions, you need to import them in your rules (see examples below). + +The following actions are supported: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Action NameDescriptionParameter TypeParameter NameParameter Description
blinkIndicatorBlink an indicator LED.intindicatorId1 for top indicator, 2 for center indicator or 3 for bottom indicator.
int[]rgbProvide an array with exactly 3 values for red, green and blue (in the range 0-255).
intblinkTimeInMsProvide the blink time in milliseconds.
fadeIndicatorFade an indicator LED in and out.intindicatorId1 for top indicator, 2 for center indicator or 3 for bottom indicator.
int[]rgbProvide an array with exactly 3 values for red, green and blue (in the range 0-255).
intfadeTimeInMsProvide the fade time in milliseconds.
activateIndicatorActivate an indicator LED.intindicatorId1 for top indicator, 2 for center indicator or 3 for bottom indicator.
int[]rgbProvide an array with exactly 3 values for red, green and blue (in the range 0-255).
deactivateIndicatorDeactivate an indicator LED.intindicatorId1 for top indicator, 2 for center indicator or 3 for bottom indicator.
rebootReboot the device
sleepMake the device sleep for a number of seconds.intsecondsDevice will wake up after the specified number of seconds. Sleep can only be interrupted by a press of the select button.
upgradeUpgrade the device if a firmware update is available.
playSoundPlay a sound file saved on the device.StringmelodyThe sound file name saved in the clocks MELODIES folder (without the file extension).
playRtttlPlay a rtttl sound.StringrtttlThe rtttl string to play.
showNotificationShow a notification.StringmessageThe message to show.
StringiconThe name of the icon saved on the device that is shown with the message.
showCustomNotificationShow a notification with maximal customization options.Map<String, Object>appParamsMap that holds any parameter that is available for an Awtrix App as shown in the App Channels section of the documentation. Please use the values shown in the Action parameter column of the App Channels section as keys.
booleanholdWhether the notification should stay on the screen until the user presses the select button.
booleanwakeUpWhether the notification should wake up the device if the display is currently switched off.
booleanstackWhether the notification should be stacked on top of the previous notification or replace the currently active notification.
StringrtttlPlay the specified rtttl sound when displaying the notification.
StringrtttlPlay the specified rtttl ringtone when displaying the notification. Set to null for no sound or when the sound parameter is set.
StringsoundPlay the specified sound file when displaying the notification. Set to null for no sound or when the rtttl parameter is set.
booleanloopSoundWhether the sound should be played in a loop until the notification is dismissed.
## Full Example @@ -219,7 +380,7 @@ sitemap awtrix label="Awtrix Display" { ``` -## Actions +### Actions The binding provides various actions that can be used in rules to control the Awtrix display. To use these actions, you need to import them in your rules. diff --git a/bundles/org.openhab.binding.mqtt.awtrixlight/src/main/java/org/openhab/binding/mqtt/awtrixlight/internal/handler/AwtrixLightAppHandler.java b/bundles/org.openhab.binding.mqtt.awtrixlight/src/main/java/org/openhab/binding/mqtt/awtrixlight/internal/handler/AwtrixLightAppHandler.java index 2eb375527a958..42d9d0e3c4b1b 100644 --- a/bundles/org.openhab.binding.mqtt.awtrixlight/src/main/java/org/openhab/binding/mqtt/awtrixlight/internal/handler/AwtrixLightAppHandler.java +++ b/bundles/org.openhab.binding.mqtt.awtrixlight/src/main/java/org/openhab/binding/mqtt/awtrixlight/internal/handler/AwtrixLightAppHandler.java @@ -584,6 +584,9 @@ private void initStates() { updateState(new ChannelUID(channelPrefix + CHANNEL_TEXT_OFFSET), new QuantityType<>(this.app.getTextOffset(), Units.ONE)); + updateState(new ChannelUID(channelPrefix + CHANNEL_TEXTCASE), + new QuantityType<>(this.app.getTextCase(), Units.ONE)); + updateState(new ChannelUID(channelPrefix + CHANNEL_TOP_TEXT), this.app.getTopText() ? OnOffType.ON : OnOffType.OFF); @@ -616,9 +619,6 @@ private void initStates() { } updateState(new ChannelUID(channelPrefix + CHANNEL_PUSH_ICON), new StringType(param)); - updateState(new ChannelUID(channelPrefix + CHANNEL_TEXTCASE), - new QuantityType<>(this.app.getBlinkText(), Units.ONE)); - BigDecimal[] background = this.app.getBackground().length == 3 ? this.app.getBackground() : new BigDecimal[] { BigDecimal.ZERO, BigDecimal.ZERO, BigDecimal.ZERO }; updateState(new ChannelUID(channelPrefix + CHANNEL_BACKGROUND),