Merge remote-tracking branch 'sidoh/v1.10.0-wip' into dev

Author: bombcheck

.gitignore

@@ -6,6 +6,7 @@
 .sconsign.dblite
 /web/node_modules
 /web/build
+/web/package-lock.json
 /dist/*.bin
 /dist/docs
 .vscode/

.prepare_docs

@@ -31,18 +31,21 @@ DIST_DIR="./dist/docs"
 BRANCHES_DIR="${DIST_DIR}/branches"
 API_SPEC_FILE="${DOCS_DIR}/openapi.yaml"
 
+rm -rf "${DIST_DIR}"
+
 redoc_bundle_file=$(mktemp)
 git_ref_version=$(git describe --always)
 branch_docs_dir="${BRANCHES_DIR}/${git_ref_version}"
 
 # Build Redoc bundle (a single HTML file)
-redoc-cli bundle ${API_SPEC_FILE} -o ${redoc_bundle_file}
+redoc-cli bundle ${API_SPEC_FILE} -o ${redoc_bundle_file} --title 'Milight Hub API Documentation'
 
 # Check out current stuff from gh-pages (we'll append to it)
 git fetch origin 'refs/heads/gh-pages:refs/heads/gh-pages'
 git checkout gh-pages -- branches || prepare_docs_log "Failed to checkout branches from gh-pages, skipping..."
 
 if [ -e "./branches" ]; then
+  mkdir -p "${DIST_DIR}"
   mv "./branches" "${BRANCHES_DIR}"
 else
   mkdir -p "${BRANCHES_DIR}"
@@ -62,7 +65,7 @@ cp "${redoc_bundle_file}" "${branch_docs_dir}/index.html"
 
 # Update `latest` symlink to this branch
 rm -rf "${BRANCHES_DIR}/latest"
-ln -s "${branch_docs_dir}" "${BRANCHES_DIR}/latest"
+ln -s "${git_ref_version}" "${BRANCHES_DIR}/latest"
 
 # Create a JSON file containing a list of all branches with docs (we'll
 # have an index page that renders the list).

README.md

@@ -116,26 +116,6 @@ If it does not work as expected see [Troubleshooting](https://github.com/sidoh/e
 
 If you need to pair some bulbs, how to do this is [described in the wiki](https://github.com/sidoh/esp8266_milight_hub/wiki/Pairing-new-bulbs).
 
-## LED Status
-
-Some ESP boards have a built-in LED, on pin #2.  This LED will flash to indicate the current status of the hub:
-
-* Wifi not configured: Fast flash (on/off once per second).  See [Configure Wifi](#configure-wifi) to configure the hub.
-* Wifi connected and ready: Occasional blips of light (a flicker of light every 1.5 seconds).
-* Packets sending/receiving: Rapid blips of light for brief periods (three rapid flashes).
-* Wifi failed to configure: Solid light.
-
-In the setup UI, you can turn on "enable_solid_led" to change the LED behavior to:
-
-* Wifi connected and ready: Solid LED light
-* Wifi failed to configure: Light off
-
-Note that you must restart the hub to affect the change in "enable_solid_led".
-
-You can configure the LED pin from the web console.  Note that pin means the GPIO number, not the D number ... for example, D2 is actually GPIO4 and therefore its pin 4.  If you specify the pin as a negative number, it will invert the LED signal (the built-in LED on pin 2 is inverted, so the default is -2).
-
-If you want to wire up your own LED on a pin, such as on D2/GPIO4, put a wire from D2 to one side of a 220 ohm resister.  On the other side, connect it to the positive side (the longer wire) of a 3.3V LED.  Then connect the negative side of the LED (the shorter wire) to ground.  If you use a different voltage LED, or a high current LED, you will need to add a driver circuit.
-
 ## Device Aliases
 
 You can configure aliases or labels for a given _(Device Type, Device ID, Group ID)_ tuple.  For example, you might want to call the RGB+CCT remote with the ID `0x1111` and the Group ID `1` to be called `living_room`.  Aliases are useful in a couple of different ways:
@@ -150,7 +130,7 @@ The REST API is specified using
 
 [openapi.yaml](openapi.yaml) contains the raw spec, created using [OpenAPI v3](https://swagger.io/docs/specification/about/).
 
-[You can view generated documentation for the master branch here.](https://sidoh.github.io/esp8266_milight_hub/master)
+[You can view generated documentation for the master branch here.](https://sidoh.github.io/esp8266_milight_hub/branches/latest)
 
 [Docs for other branches can be found here](https://sidoh.github.io/esp8266_milight_hub)
 
@@ -244,6 +224,61 @@ You can add an arbitrary number of UDP gateways through the REST API or through
 
 You can select between versions 5 and 6 of the UDP protocol (documented [here](http://www.limitlessled.com/dev/)). Version 6 has support for the newer RGB+CCT bulbs and also includes response packets, which can theoretically improve reliability. Version 5 has much smaller packets and is probably lower latency.
 
+## Transitions
+
+Transitions between two given states are supported.  Depending on how transition commands are being issued, the duration and smoothness of the transition are both configurable.  There are a few ways to use transitions:
+
+#### RESTful `/transitions` routes
+
+These routes are fully documented in the [REST API documentation](https://sidoh.github.io/esp8266_milight_hub/branches/latest/#tag/Transitions).
+
+#### `transition` field when issuing commands
+
+When you issue a command to a bulb either via REST or MQTT, you can include a `transition` field.  The value of this field specifies the duration of the transition, in seconds (non-integer values are supported).
+
+For example, the command:
+
+```json
+{"brightness":255,"transition":60}
+```
+
+will transition from whatever the current brightness is to `brightness=255` over 60 seconds.
+
+#### Notes on transitions
+
+* espMH's transitions should work seamlessly with [HomeAssistant's transition functionality](https://www.home-assistant.io/components/light/).
+* You can issue commands specifying transitions between many fields at once.  For example:
+  ```json
+  {"brightness":255,"kelvin":0,"transition":10.5}
+  ```
+  will transition from current values for brightness and kelvin to the specified values -- 255 and 0 respectively -- over 10.5 seconds.
+* Color transitions are supported.  Under the hood, this is treated as a transition between current values for r, g, and b to the r, g, b values for the specified color.  Because milight uses hue-sat colors, this might not behave exactly as you'd expect for all colors.
+* You can transition to a given `status` or `state`.  For example,
+  ```json
+  {"status":"ON","transition":10}
+  ```
+  will turn the bulb on, immediately set the brightness to 0, and then transition to brightness=255 over 10 seconds.  If you specify a brightness value, the transition will stop there instead of 255.
+
+## LED Status
+
+Some ESP boards have a built-in LED, on pin #2.  This LED will flash to indicate the current status of the hub:
+
+* Wifi not configured: Fast flash (on/off once per second).  See [Configure Wifi](#configure-wifi) to configure the hub.
+* Wifi connected and ready: Occasional blips of light (a flicker of light every 1.5 seconds).
+* Packets sending/receiving: Rapid blips of light for brief periods (three rapid flashes).
+* Wifi failed to configure: Solid light.
+
+In the setup UI, you can turn on "enable_solid_led" to change the LED behavior to:
+
+* Wifi connected and ready: Solid LED light
+* Wifi failed to configure: Light off
+
+Note that you must restart the hub to affect the change in "enable_solid_led".
+
+You can configure the LED pin from the web console.  Note that pin means the GPIO number, not the D number ... for example, D2 is actually GPIO4 and therefore its pin 4.  If you specify the pin as a negative number, it will invert the LED signal (the built-in LED on pin 2 is inverted, so the default is -2).
+
+If you want to wire up your own LED on a pin, such as on D2/GPIO4, put a wire from D2 to one side of a 220 ohm resister.  On the other side, connect it to the positive side (the longer wire) of a 3.3V LED.  Then connect the negative side of the LED (the shorter wire) to ground.  If you use a different voltage LED, or a high current LED, you will need to add a driver circuit.
+
 ## Development
 
 This project is developed and built using [PlatformIO](https://platformio.org/).

dist/index.html.gz.h

@@ -771,6 +771,7 @@ components:
       - group_id
       - device_type
       - oh_color
+      - hex_color
       description: >
         Defines a field which is a part of state for a particular light device.  Most fields are self-explanatory, but documentation for each follows:
 
@@ -786,6 +787,8 @@ components:
 
         * `oh_color` - same as `color` with a format compatible with [OpenHAB's colorRGB channel type](https://www.openhab.org/addons/bindings/mqtt.generic/#channel-type-colorrgb-colorhsb).
 
+        * `hex_color` - same as `color` except in hex color (e.g., `#FF0000` for red).
+
         * `device_id` / `device_type` / `group_id` - this information is in the MQTT topic or REST route, but can be included in the payload in the case that processing the topic or route is more difficult.
     DeviceId:
       type: array

docs/openapi.yaml

@@ -40,6 +40,14 @@ void HomeAssistantDiscoveryClient::addConfig(const char* alias, const BulbId& bu
   config[F("name")] = alias;
   config[F("command_topic")] = mqttClient->bindTopicString(settings.mqttTopicPattern, bulbId);
   config[F("state_topic")] = mqttClient->bindTopicString(settings.mqttStateTopicPattern, bulbId);
+  JsonObject deviceMetadata = config.createNestedObject(F("device"));
+
+  deviceMetadata[F("manufacturer")] = F("esp8266_milight_hub");
+  deviceMetadata[F("sw_version")] = QUOTE(MILIGHT_HUB_VERSION);
+
+  JsonArray identifiers = deviceMetadata.createNestedArray(F("identifiers"));
+  identifiers.add(ESP.getChipId());
+  bulbId.serialize(identifiers);
 
   // HomeAssistant only supports simple client availability
   if (settings.mqttClientStatusTopic.length() > 0 && settings.simpleMqttClientStatus) {
@@ -57,36 +65,48 @@ void HomeAssistantDiscoveryClient::addConfig(const char* alias, const BulbId& bu
   JsonArray effects = config.createNestedArray(F("effect_list"));
   effects.add(MiLightCommandNames::NIGHT_MODE);
 
-  // These bulbs support RGB color
+  // These bulbs support switching between rgb/white, and have a "white_mode" command
   switch (bulbId.deviceType) {
     case REMOTE_TYPE_FUT089:
-    case REMOTE_TYPE_RGB:
     case REMOTE_TYPE_RGB_CCT:
     case REMOTE_TYPE_RGBW:
-      config[F("rgb")] = true;
+      effects.add("white_mode");
       break;
     default:
       break; //nothing
   }
 
-  // These bulbs support adjustable white values
+  // All bulbs except CCT have 9 modes.  FUT029 and RGB/FUT096 has 9 modes, but they
+  // are not selectable directly.  There are only "next mode" commands.
   switch (bulbId.deviceType) {
     case REMOTE_TYPE_CCT:
+    case REMOTE_TYPE_RGB:
+    case REMOTE_TYPE_FUT020:
+      break;
+    default:
+      addNumberedEffects(effects, 0, 8);
+      break;
+  }
+
+  // These bulbs support RGB color
+  switch (bulbId.deviceType) {
     case REMOTE_TYPE_FUT089:
-    case REMOTE_TYPE_FUT091:
+    case REMOTE_TYPE_RGB:
     case REMOTE_TYPE_RGB_CCT:
-      config[GroupStateFieldNames::COLOR_TEMP] = true;
+    case REMOTE_TYPE_RGBW:
+      config[F("rgb")] = true;
       break;
     default:
       break; //nothing
   }
 
-  // These bulbs support switching between rgb/white, and have a "white_mode" command
+  // These bulbs support adjustable white values
   switch (bulbId.deviceType) {
+    case REMOTE_TYPE_CCT:
     case REMOTE_TYPE_FUT089:
+    case REMOTE_TYPE_FUT091:
     case REMOTE_TYPE_RGB_CCT:
-    case REMOTE_TYPE_RGBW:
-      effects.add("white_mode");
+      config[GroupStateFieldNames::COLOR_TEMP] = true;
       break;
     default:
       break; //nothing
@@ -144,4 +164,10 @@ String HomeAssistantDiscoveryClient::bindTopicVariables(const String& topic, con
   boundTopic.replace(":group_id", String(bulbId.groupId));
 
   return boundTopic;
+}
+
+void HomeAssistantDiscoveryClient::addNumberedEffects(JsonArray& effectList, uint8_t start, uint8_t end) {
+  for (uint8_t i = start; i <= end; ++i) {
+    effectList.add(String(i));
+  }
 }

lib/MQTT/HomeAssistantDiscoveryClient.cpp

@@ -20,4 +20,5 @@ class HomeAssistantDiscoveryClient {
 
   String buildTopic(const BulbId& bulbId);
   String bindTopicVariables(const String& topic, const char* alias, const BulbId& bulbId);
+  void addNumberedEffects(JsonArray& effectList, uint8_t start, uint8_t end);
 };

lib/MQTT/HomeAssistantDiscoveryClient.h

@@ -10,6 +10,8 @@
 
 using namespace std::placeholders;
 
+static const uint8_t STATUS_UNDEFINED = 255;
+
 const char* MiLightClient::FIELD_ORDERINGS[] = {
   // These are handled manually
   // GroupStateFieldNames::STATE,
@@ -20,6 +22,7 @@ const char* MiLightClient::FIELD_ORDERINGS[] = {
   GroupStateFieldNames::TEMPERATURE,
   GroupStateFieldNames::COLOR_TEMP,
   GroupStateFieldNames::MODE,
+  GroupStateFieldNames::EFFECT,
   GroupStateFieldNames::COLOR,
   // Level/Brightness must be processed last because they're specific to a particular bulb mode.
   // So make sure bulb mode is set before applying level/brightness.
@@ -279,7 +282,7 @@ void MiLightClient::updateColor(JsonVariant json) {
   ParsedColor color = ParsedColor::fromJson(json);
 
   if (!color.success) {
-    Serial.println(F("Error parsing JSON color"));
+    Serial.println(F("Error parsing color field, unrecognized format"));
     return;
   }
 
@@ -320,7 +323,20 @@ void MiLightClient::update(JsonObject request) {
     if (transition == 0) {
       this->updateStatus(ON);
     } else {
-      handleTransition(GroupStateField::STATUS, status, transition);
+      JsonVariant brightness = request[GroupStateFieldNames::BRIGHTNESS];
+      JsonVariant level = request[GroupStateFieldNames::LEVEL];
+
+      // The behavior for status transitions is to ramp up to max or down to min brightness.  If a
+      // brightness is specified, we shold ramp up or down to that value instead.
+      if (!brightness.isUndefined()) {
+        this->updateStatus(ON);
+        handleTransition(GroupStateField::BRIGHTNESS, brightness, transition, 0);
+      } else if (!level.isUndefined()) {
+        this->updateStatus(ON);
+        handleTransition(GroupStateField::LEVEL, level, transition, 0);
+      } else {
+        handleTransition(GroupStateField::STATUS, status, transition, 0);
+      }
     }
   }
 
@@ -330,14 +346,20 @@ void MiLightClient::update(JsonObject request) {
       JsonVariant value = request[fieldName];
 
       if (handler != FIELD_SETTERS.end()) {
-        if (transition != 0) {
-          handleTransition(
-            GroupStateFieldHelpers::getFieldByName(fieldName),
-            value,
-            transition
-          );
-        } else {
+        // No transition -- set field directly
+        if (transition == 0) {
           handler->second(this, value);
+        } else {
+          // Do not generate a brightness transition if a status field was specified.  Status will
+          // generate its own brightness transition, and generating another one will cause conflicts.
+          GroupStateField field = GroupStateFieldHelpers::getFieldByName(fieldName);
+
+          if (    !GroupStateFieldHelpers::isBrightnessField(field) // If field isn't brightness
+               || parsedStatus == STATUS_UNDEFINED                  // or if there was not a status field
+                                                                    // in the command
+          ) {
+            handleTransition(field, value, transition);
+          }
         }
       }
     }
@@ -414,7 +436,7 @@ void MiLightClient::handleCommand(JsonVariant command) {
   }
 }
 
-void MiLightClient::handleTransition(GroupStateField field, JsonVariant value, float duration) {
+void MiLightClient::handleTransition(GroupStateField field, JsonVariant value, float duration, int16_t startValue) {
   BulbId bulbId = currentRemote->packetFormatter->currentBulbId();
   GroupState* currentState = stateStore->get(bulbId);
   std::shared_ptr<Transition::Builder> transitionBuilder = nullptr;
@@ -439,22 +461,28 @@ void MiLightClient::handleTransition(GroupStateField field, JsonVariant value, f
       endColor
     );
   } else if (field == GroupStateField::STATUS || field == GroupStateField::STATE) {
-    uint8_t startLevel = 0;
+    uint8_t startLevel;
     MiLightStatus status = parseMilightStatus(value);
 
-    if (currentState->isSetBrightness()) {
+    if (startValue == FETCH_VALUE_FROM_STATE) {
       startLevel = currentState->getBrightness();
     } else if (status == ON) {
       startLevel = 0;
     } else {
       startLevel = 100;
     }
 
-    transitionBuilder = transitions.buildStatusTransition(bulbId, parseMilightStatus(value), startLevel);
+    transitionBuilder = transitions.buildStatusTransition(bulbId, status, startLevel);
   } else {
-    uint16_t currentValue = currentState->getParsedFieldValue(field);
+    uint16_t currentValue;
     uint16_t endValue = value;
 
+    if (startValue == FETCH_VALUE_FROM_STATE) {
+      currentValue = currentState->getParsedFieldValue(field);
+    } else {
+      currentValue = startValue;
+    }
+
     transitionBuilder = transitions.buildFieldTransition(
       bulbId,
       field,
@@ -598,7 +626,7 @@ JsonVariant MiLightClient::extractStatus(JsonObject object) {
 
 uint8_t MiLightClient::parseStatus(JsonVariant val) {
   if (val.isUndefined()) {
-    return 255;
+    return STATUS_UNDEFINED;
   }
 
   return parseMilightStatus(val);

lib/MiLight/MiLightClient.cpp

@@ -37,6 +37,9 @@ namespace TransitionParams {
 
 class MiLightClient {
 public:
+  // Used to indicate that the start value for a transition should be fetched from current state
+  static const int16_t FETCH_VALUE_FROM_STATE = -1;
+
   MiLightClient(
     RadioSwitchboard& radioSwitchboard,
     PacketSender& packetSender,
@@ -93,7 +96,7 @@ class MiLightClient {
   void handleCommand(JsonVariant command);
   void handleCommands(JsonArray commands);
   bool handleTransition(JsonObject args, JsonDocument& responseObj);
-  void handleTransition(GroupStateField field, JsonVariant value, float duration);
+  void handleTransition(GroupStateField field, JsonVariant value, float duration, int16_t startValue = FETCH_VALUE_FROM_STATE);
   void handleEffect(const String& effect);
 
   void onUpdateBegin(EventHandler handler);