jeff-winn/homebridge-automower-platform

A platform plugin for Homebridge to connect your Husqvarna Automower and Gardena Smart (BETA) robotic lawn mowers to Apple HomeKit.

I'm primarily focused on C# and .NET technologies, but it's always fun to branch out and learn new things!

Lately I've been working in the Java stack.

homebridge-automower-platform's Issues

Add support for i18n

As a user, when English isn’t my first language I have no way of changing the language used within the strings my preferred language.

it would be great if the plug-in supported internationalization for strings used as messages in errors to help me better understand what is happening.

By moving the strings into something else, the data abstraction would enable support for other languages.

Mowers should be purged

As a user, the mowers I remove from my account should be removed from the bridge automatically.

If I am unable to identify which mowers I do want to connect to the platform, this will be needed to keep the accessories those which I actually have.

Debug should use the environment variable

As a user, staying consistent with how I enable debug mode on plugins can be extremely valuable. Currently the plug-in uses a custom config setting to enable debug mode.

This mechanism should use the DEBUG environment variable provided by Homebridge rather than a custom config entry.

Cannot handle 429 responses

There has been a 429 response received from Husqvarna due to too many requests received.

Their documentation says one request per second, so most likely it was the auth->get mowers calls that caused the issue.

The automower services will need to handle 429 responses to perform an automatic delay + retry to make another attempt to perform the action needed.

Expected Behavior

• The client is able to do the action against the api

Actual Behavior

• The client received a 429 response and handles it similarly to a 500 generic error response.

Retrieve list of mowers

The user interface will need a means of accessing a list of mowers as available options to control within the platform.

Quality gate failed

With the merge that abstracted fetch the clients were removed from the exclusions list for code coverage.

The overall coverage level has dropped below 80% so new tests will need to be added.

Schedule switch not changing values

When the schedule is set such that the mower will run constantly within the Husqvarna app and HomeKit is in control of the calendar, the switch never changes to on when being set to on.

Expected Behavior

• Given the schedule switch is in the off position
• When the schedule switch is turned on
• Then there is a message logged indicating the switch has been turned on

Actual Behavior

• Given the schedule switch is in the off position
• When the schedule switch is turned on
• Then the schedule switch never logs a message and the value does not change

Document account setup

As a user, knowing where I need to go to create an account would be helpful in easing on boarding of the plug-in.

The readme needs to be updated to contain the instructions, along with the instructions showing up on the npmjs.com website

Quality gate should be on PR

As a developer, having the sonar scans can be helpful in keeping code consistently high quality.

However having the sonar scans enforcing quality on development branches just causes lots of builds to fail unnecessarily. This would mean dev branches are only pushed when done, defeating the purpose of the scan.

The quality gate check step should be relocated so it only occurs on PR changes, and not on push.

Sensor needed when device is mowing

As an owner, knowing when the device is actively mowing in the yard could be very helpful.

The motion sensor service contains a motion detected characteristic that should be used for this mechanism.

Design Considerations

• The data should be the mower activity, however there could be multiple values used.
• This may have to be more of an “is the mower moving in the yard?” question rather than just mowing.
• If the device has been paused while in operation, this sensor should indicate not in motion.

Acceptance Criteria

• When the mower is leaving the charge station the motion sensor is active.
• When the mower is mowing the motion sensor is active.
• When the mower is going home the motion sensor is active.
• When the mower is stuck in the garden the motion sensor is not active.

OAuthToken should be limited to the token manager

As a developer, the OAuthToken model appears to be used in too many places around the codebase for parts that don’t need the entire token.

An AuthToken model should be created that contains two values:

• The access token
• The token provider

This will ensure the OAuthTokenManager can retain ownership of the data and the application only knows about what it needs to know.

Design Considerations

• The authentication client should own the OAuthToken model
• It may make more sense to move the authentication client in the authentication package

Sensor needed when faulted

As a user, being able to trigger actions within HomeKit when the mower encounters a fault could be extremely helpful.

The motion sensor service contains a fault characteristic that should be used for this mechanism.

Need workflow templates

The stock template for Homebridge plug-ins contains workflow templates for GitHub.

These should be added to the project.

Sensor needed when leaving

As a user, knowing when the mower is leaving the charge station would allow me to setup automation (for example a door on the mower house).

A sensor should be added such that when the mower is leaving the sensor is turned on. Once the mower has left and transitioned to mowing, then the sensor should be turned off.

Need build matrix for multiple versions of node

One of the requirements for homebridge verified status is supporting all LTS versions of node.

Currently the only version being targeted is 16 within the CI pipeline.

A matrix should be setup to build all versions supported by Homebridge to ensure compatibility.

Acceptance Criteria
The following versions of node are ran through the build pipeline:

• 14
• 16
• 18

Need means of configuring the mowers

As a user, being able to identify which mower(s) I have on my account would be helpful in setting up the bridge connection.

To start with, a simple data entry for the following would be needed:

• The user name and password
• The mower identifier
• The app key from the developer portal (optional)

Add support for event streaming

As a developer, I need to be able to receive status updates from Husqvarna so I don’t need to poll their web api for changes to the mower.

I need a client setup that can handle event based callbacks based on the event type.

https://developer.husqvarnagroup.cloud/apis/Automower+Connect+API#/websocket

Need better documentation

As a potential user, being able to read about the plug-in can be a deciding factor whether the plug-in will be selected for installation .

There is currently very little documentation in the readme about the project.

Design Considerations

• A GitHub pages website could be helpful with users self troubleshooting the plug-in.

Acceptance Criteria

• There should be descriptions of available services.
• The full config sample should be displayed (in case someone wants to set it up manually)
• How to enable debug logging within the user interface.
• Errors the user must handle should contain error codes they can use on the docs to find the KB article how to fix it.

Must allow disabling the mower schedule

The primary feature should be enabling or disabling the schedule of the mower.

Additional design considerations

• This should utilize the ParkUntilFurtherNotice and ResumeSchedule actions against a mower.
• The switch will need to take into account whether the mower is parked indefinitely upon startup.

Acceptance Criteria

• Upon disabling the switch, the mower schedule will be disabled.
• Upon enabling the switch, the mower schedule will be enabled.
• Upon restarting homebridge the current state of the mower will need to be determined.
• When controlling the mower externally by the Husqvarna app, the switch should be updated accordingly.
• Any strings which will be displayed within HomeKit that come with the plug-in must be i18n supported.

Determine what kind of accessory should be used

As a developer, the kind of accessories and characteristics exposed from the platform is critical in providing a smooth integration point.

The type of accessory and characteristics needs to be determined.

Clients need to throw errors for 401s

An error specific to 401s need to be thrown when the client is unauthorized.

This will allow the services using the token manager to catch the error, flag it as invalid, and attempt a retry before breaking themselves.

The platform needs to be able to load

The platform should be able to load correctly under the proper plugin name.

Mowing should be controlled by a switch

As a user, I may want the mower to just go out mowing and control it manually. An on/off switch needs to be added to control the mower directly.

Design Considerations

• On should signal the mower to mow for an hour.
• Off should signal the mower to go back to base.
• A timer should be used while the mower switch is on to tell the mower to mow for another hour.

Acceptance Criteria

• The documentation should be changed to show how to setup mowing by the switch.
• The documentation should be changed to show how to setup mowing by a schedule.
• The switch name needs to be changed to just the name of the mower rather than including the switch name.

Changes to user facing switches should be logged

As a user, when I’m trying to figure out what is happening with a switch it would be helpful to see when the switch is changing state.

Currently the switch does operate correctly, but no log entries are made when the value is being changed.

Passwords should not be visible

The password for a platform instance is directly displayed on the screen. This should not be allowed.

For an example how to hide the value, see the following link:
https://github.com/hjdhjd/homebridge-myq/blob/master/config.schema.json

Unable to refresh token and failing to login again when token invalid

The following errors were seen on the server while running this evening. It appears there is an issue with refreshing the token.

Expected Behavior:

• The token gets invalidated
• The authentication client gets a completely new token and throws out the old token
• The new token is used for subsequent calls to the APIs

Actual Behavior:

• The token gets invalidated
• The authentication client tries to refresh the old token
• The refresh fails, and the token is not completely thrown out
• The authentication client repeatedly tries to refresh the old token

See the following for a sample of the logs:

[6/23/2022, 6:00:10 PM] [Homebridge Automower Platform] Checking keep alive for the client stream...
[6/23/2022, 6:00:10 PM] [Homebridge Automower Platform] The stream somehow got disconnected; proceed with reconnect.
[6/23/2022, 6:00:10 PM] [Homebridge Automower Platform] Attempting to open a connection...
[6/23/2022, 6:00:10 PM] [Homebridge Automower Platform] Sending request [1/5]: 8b431637-1810-4f57-873c-2db1bd6bc1a9
 {"url":"https://api.authentication.husqvarnagroup.dev/v1/oauth2/token","method":"POST","headers":{"Content-Type":"application/x-www-form-urlencoded;charset=UTF-8"},"body":"client_id=__REDACTED__&grant_type=refresh_token&refresh_token=__REDACTED__"}
[6/23/2022, 6:00:10 PM] [Homebridge Automower Platform] Received response: 8b431637-1810-4f57-873c-2db1bd6bc1a9
 {"status":400,"statusText":"Bad Request","body":{"error":"invalid_grant","error_description":"Failed to find token","error_code":"token.not.found"}}
[6/23/2022, 6:00:10 PM] [Homebridge Automower Platform] An unexpected error occurred while keeping the client stream alive. BadOAuthTokenError: The access token supplied was invalid.
    at AuthenticationClientImpl.throwIfBadToken (/homebridge/node_modules/.pnpm/[email protected]/node_modules/homebridge-automower-platform/dist/clients/authenticationClient.js:104:19)
    at AuthenticationClientImpl.<anonymous> (/homebridge/node_modules/.pnpm/[email protected]/node_modules/homebridge-automower-platform/dist/clients/authenticationClient.js:96:18)
    at Generator.next (<anonymous>)
    at fulfilled (/homebridge/node_modules/.pnpm/[email protected]/node_modules/homebridge-automower-platform/dist/clients/authenticationClient.js:5:58)
    at runMicrotasks (<anonymous>)
    at processTicksAndRejections (node:internal/process/task_queues:96:5) {
  errorCode: 'ERR0002'
}
[6/23/2022, 6:01:10 PM] [Homebridge Automower Platform] Checking keep alive for the client stream...
[6/23/2022, 6:01:10 PM] [Homebridge Automower Platform] The stream somehow got disconnected; proceed with reconnect.
[6/23/2022, 6:01:10 PM] [Homebridge Automower Platform] Attempting to open a connection...
[6/23/2022, 6:01:10 PM] [Homebridge Automower Platform] Sending request [1/5]: 3b99e3af-9a01-4e8f-b133-7b514adfd9fa
 {"url":"https://api.authentication.husqvarnagroup.dev/v1/oauth2/token","method":"POST","headers":{"Content-Type":"application/x-www-form-urlencoded;charset=UTF-8"},"body":"client_id=__REDACTED__&grant_type=refresh_token&refresh_token=__REDACTED__"}
[6/23/2022, 6:01:11 PM] [Homebridge Automower Platform] Received response: 3b99e3af-9a01-4e8f-b133-7b514adfd9fa
 {"status":400,"statusText":"Bad Request","body":{"error":"invalid_request","error_description":"Too many login-attempts for this user, please try again later","error_code":"too.many.failed.login.attempts"}}
[6/23/2022, 6:01:11 PM] [Homebridge Automower Platform] An unexpected error occurred while keeping the client stream alive. BadOAuthTokenError: The access token supplied was invalid.
    at AuthenticationClientImpl.throwIfBadToken (/homebridge/node_modules/.pnpm/[email protected]/node_modules/homebridge-automower-platform/dist/clients/authenticationClient.js:104:19)
    at AuthenticationClientImpl.<anonymous> (/homebridge/node_modules/.pnpm/[email protected]/node_modules/homebridge-automower-platform/dist/clients/authenticationClient.js:96:18)
    at Generator.next (<anonymous>)
    at fulfilled (/homebridge/node_modules/.pnpm/[email protected]/node_modules/homebridge-automower-platform/dist/clients/authenticationClient.js:5:58)
    at runMicrotasks (<anonymous>)
    at processTicksAndRejections (node:internal/process/task_queues:96:5) {
  errorCode: 'ERR0002'

Need service to control the access token

With the token expiring automatically or forcibly, the authentication service would need to…

• Interact with the Authentication client
• Handle retrieving an access token.
• Receive signals from other services when the token is invalidated (which allows the client to signal it when a 401 occurs).

The last requirement means the service will likely be injected into the other client(s) so it can be made aware of the responses.

Platforms should have names

As a user, if I’m running multiple Automower accounts from the same Homebridge it can be hard to determine which account is having issues and fixing it.

The platform should allow me to change the name from the default “Homebridge Automower Platform” to something more meaningful.

Plug-in should be verified

As a user, the verified tag can significantly improve my potential use of the plug-in.

If this is going to be deployed on NPM so my device can access it, I’d prefer if the plug-in can be verified by the homebridge team.

Failed to run on all LTS versions of Node.js

The plug-in has been reviewed by the Homebridge team and failed to run on both Node.js 14 and 16 (both LTS versions) as required by the Homebridge team.

Expected Behavior

• The plug-in does run on Node.js 14.
• The plug-in does run on Node.js 16.
• The plug-in does run on Node.js 18.

Acceptance Criteria

• All expected behaviors are satisfied.
• Update the nodejs engine to require 14.x rather than 12.x.
• Update the homebridge engine version to the lowest version of 1.4 that is supported.

Homepage should be set to the documentation

Within the package.json file the url points to the Git repo twice.

The homepage should be the docs site.

Overriding schedule disables schedule switch

As a user, if I toggle the schedule on and then force the mower to mow, the switch even though the schedule is still active shows as being off.

Expected behavior
The switch should remain on even if the mower has had the schedule temporarily overridden.

Mowers should report battery levels

The battery service should be supported for each mower accessory.

Also, the following characteristics are needed:

• Battery level
• Charging state
• Low battery

Stream disconnects should immediately reconnect

As a user, when the Husqvarna web socket is disconnected outside of the control of the api, if a disconnect does occur the plug-in should immediately begin reconnect procedures.

When a disconnect occurs, the keep alive notices it has been disconnected and then reconnects a minute later.

Acceptance Criteria

• Triggers existing reconnect procedure when connection is disrupted.
• Uses the existing keep alive procedure for any subsequent reconnect attempts if first reconnect attempt fails.
• Prevents any exceptions from being unhandled as it would crash the Homebridge process.

Mowers should be accessories

The main purpose of the platform is to add and remove accessories dynamically.

Any mowers connected to the account should be registered as accessories.

Need to be able to access the Husqvarna platform

The authentication API needs to be implemented.

Unable to debug

As a server admin, being able to specify which plug-in I want to debug is extremely valuable.

Currently to debug, the plug-in requires the -D mode be used at the Homebridge level which means all plugins are put into debug mode.

This means the logs are likely unusable for debugging just one if there are many plugins installed.

Setup sonar scanning

As a developer, having tooling aid me with ensuring the quality of the code being written is extremely helpful.

The sonar scanner should be used to scan the code and ensure quality controls are being adhered to within the SDLC.

Platform should allow for multiple accounts

Some users may have multiple accounts associated. Given there is no technical limitation that should require only a single instance of the platform, multiple instances should be made available.

Schedule switch can throw errors

As part of the homebridge verification process, no errors can make their way back to Homebridge.

The schedule switch is currently able to throw an error back to Homebridge by way of the onSet method call.

This needs to be prevented, along with changing the status to an appropriate error response.

Wrong error message when app key has been removed

As a user, they have full control over the config file that loads the plugin. If the user is editing the configuration by hand, or has tampered with the configuration the plugin sends the wrong error message back indicating bad username and/or password.

This really should instead indicate that the app key is required.

Builds failing consistently

There appears to be an issue with the pipeline wherein it fails randomly but keeps occurring rather consistently.

It appears that SonarCloud sends a 404 back which breaks their tool, my only suspicion is now that there is a matrix too many requests are occurring at once.

May need to break the build down and do the reporting in a separate track.

Switch needed to pause the mower

As a user being able to pause the mower would be extremely helpful.

It has already ran over (and destroyed) a splash pad that could have been prevented had my wife been able to tell the mower to pause temporarily.

Sensor needed when arriving

As a user, knowing when the mower is headed home would enable me to setup automation (for example, a door on the mower house could be opened).

When the mower transitions into the going home state, the sensor should be enabled. When the mower has arrived the sensor should be turned off.

Logging not showing as colorized from the Homebridge UI

After #50 the colorized text no longer appears as expected within the Homebridge user interface.

Expected behavior:
The colorized text should match what is shown within the user interface by other plugins.

Sensor needed when device is lifted

As an owner, being notified when the device is lifted or tampered with could be useful from an automation perspective. Even more so with the mower running at night.

The motion sensor service contains a tampered characteristic that should be used for this mechanism.

Dependencies should be injected

Due to the complexity of the object graph dependency injection should be used to assist with object creation.

Inversify was being used previously but it also caused issues during testing.

Fails to refresh before token times out

There is an issue with the token refresh that's causing the client to fail to recover once the token has expired. This appears to be due to the client attempting to refresh the token at the time the token has expired - rather than prior to the token expiring.

This cannot be confirmed due to a lack of logging, but based on the code paths this is likely what's happening.

Expected Behavior

• Given a previously successful login.
• When the token is supposed to expire.
• Then the token is refreshed successfully.

Actual Behavior

• Given a previously successful login.
• When the token expires.
• Then the token fails to refresh successfully because the token has already expired when being refreshed.

Other Acceptance Criteria

• When the debug logging is enabled
• Then the logs should indicate when the token has been refreshed.

Reorganize the services

As a designer keeping the services for the mower control separate from the services to interact with homebridge should help keep the responsibilities separated.

The mower related services need to be moved into an automower folder off the root of services.

Homebridge restarted upon disconnect

For some unknown reason, the event stream disconnected on the server and then threw a 400 indicating a bad request.

This in turn crashed the Homebridge process and forced a restart.

See attached server logs: restart.log