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.

Sign up for GitHub

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

Jump to bottom

Add doc to sys/panel endpoint #85

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Add doc to sys/panel endpoint #85

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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 local.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -72,6 +72,7 @@ x-tagGroups:
- Time
- Power
- Locale
- Panel
- name: Debug
tags:
- Database
Expand Down
2 changes: 2 additions & 0 deletions local/paths.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -110,3 +110,5 @@
$ref: ../firmware/paths.yaml#/BackupPut
delete:
$ref: ../firmware/paths.yaml#/BackupDelete
/v2/sys/panel:
$ref: ../sys/paths.yaml#/PanelPath
46 changes: 46 additions & 0 deletions sys/paths.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -93,3 +93,49 @@ TimePatch:
disabled.
tags:
- Time
PanelPath:
get:
$ref: ../sys/paths.yaml#/PanelGet
patch:
$ref: ../sys/paths.yaml#/PanelPatch
PanelGet:
responses:
'200':
description: Get Panel Info
content:
application/json:
schema:
$ref: schemas.yaml#/Panel
properties:
keypad_mode:
summary: Get panel info
description: |
Get current panel information.

**NOTE:** The endpoint `sys/panel` is available only for Smart by bond with ID
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

(Added in v3.13)

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Here's an attempt at a paragraph for the GET endpoint. Nothing special needed for PATCH. Ideally there would be a description for the endpoint as a whole but I don't see how to do it, so I've just put this kind of background in the GET section. --- Alternatively it could go up in the preliminary chapters.

The panel endpoint is used to adjust the behavior of the front-panel on certain Smart by Bond products. In particular, in-wall fan and light switch products can be set to "Keypad Mode" where key presses send BondSync messages (similar to a Sidekick keypad) rather than directly controlling the attached light or fan device. This is intended to be used in multiway switch configurations. To set up "3-way", enable Keypad Mode on the switch which does not directly control the device. The switch will then appear as a Sidekick and can be channel-linked to the main switch which does directly control the appliance.

starting with TW or KW (in-wall switches).
tags:
- Panel
PanelPatch:
responses:
'200':
description: Changed Panel Info
content:
application/json:
schema:
$ref: schemas.yaml#/Panel
'400':
$ref: ../common/responses.yaml#/BadRequest
'500':
$ref: ../common/responses.yaml#/InternalServerError
summary: Patch panel info
description: |
Patch panel info, available fields:
- `"keypad_mode"`: define in-wall switch mode of operation...
- If `true` device operate as keypad, streaming out bond sync actions that
controls another device. A new sidekick named bondid and same location is implicity
created under sidekicks endpoint. After reboot `devices/1` is no longer available.
- If set to `false` implicit delete the sidekick created and behave as a regular switch,
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Preferably this info goes in the description in the schema.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Better here to have a paragraph description more of the why than the what & how.

no more streaming messages. After reboot the `devicse/1` is available back again
tags:
- Panel
8 changes: 8 additions & 0 deletions sys/schemas.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -58,3 +58,11 @@ Time:
`null` if unset.

See: https://en.wikipedia.org/wiki/Maidenhead_Locator_System
Panel:
type: object
properties:
keypad_mode:
example: true
type: boolean
decription: |
If true set switch to keypad mode.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You can add some more detail here on the true/false cases.