diff --git a/.github/ISSUE_TEMPLATE.md b/.github/ISSUE_TEMPLATE.md deleted file mode 100644 index df14c9ead..000000000 --- a/.github/ISSUE_TEMPLATE.md +++ /dev/null @@ -1,46 +0,0 @@ - - - - -# Bug Report -## What happened - -## What did you expect to happen - -## How to reproduce it (minimal and precise) - -## Debug Info -Zigbee2MQTT version: -Adapter hardware: CC2531, CC2530, CC26X2R1 or CC1352P-2 -Adapter firmware version: diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md deleted file mode 100644 index 9238752a2..000000000 --- a/.github/ISSUE_TEMPLATE/feature_request.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -name: Feature request -about: Suggest an idea for this project -title: '' -labels: feature request -assignees: '' - ---- - -## Is your feature request related to a problem? Please describe -A clear and concise description of what the problem is. Ex. I'm always frustrated when [...] - -## Describe the solution you'd like -A clear and concise description of what you want to happen. - -## Describe alternatives you've considered -A clear and concise description of any alternative solutions or features you've considered. - -## Additional context -Add any other context or screenshots about the feature request here. diff --git a/.github/ISSUE_TEMPLATE/feature_request.yaml b/.github/ISSUE_TEMPLATE/feature_request.yaml new file mode 100644 index 000000000..f4eab5ec4 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yaml @@ -0,0 +1,38 @@ +name: Feature request +description: Suggest an idea for this project +title: "[Feature request]: " +labels: [feature request] +body: + - type: markdown + attributes: + value: | + **IMPORTANT:** Before submitting: + - Is your feature request related to the fronted? Then click [here](https://github.com/nurikk/zigbee2mqtt-frontend/issues/new?assignees=&labels=&template=feature_request.md&title=) + - type: textarea + id: textarea1 + attributes: + label: Is your feature request related to a problem? Please describe + placeholder: A clear and concise description of what the problem is. Ex. I'm always frustrated when [...] + validations: + required: true + - type: textarea + id: textarea2 + attributes: + label: Describe the solution you'd like + placeholder: A clear and concise description of what you want to happen. + validations: + required: true + - type: textarea + id: textarea3 + attributes: + label: Describe alternatives you've considered + placeholder: A clear and concise description of any alternative solutions or features you've considered. + validations: + required: true + - type: textarea + id: textarea4 + attributes: + label: Additional context + placeholder: Add any other context or screenshots about the feature request here. + validations: + required: true diff --git a/.github/ISSUE_TEMPLATE/new_device_support.md b/.github/ISSUE_TEMPLATE/new_device_support.md deleted file mode 100644 index 9674ff041..000000000 --- a/.github/ISSUE_TEMPLATE/new_device_support.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -name: New device support request -about: Request support for a new device -title: '' -labels: new device support -assignees: '' - ---- - - - -## Information about the device + link -.. - -## data/database.db entry of the device -.. diff --git a/.github/ISSUE_TEMPLATE/new_device_support.yaml b/.github/ISSUE_TEMPLATE/new_device_support.yaml new file mode 100644 index 000000000..198fbd1fc --- /dev/null +++ b/.github/ISSUE_TEMPLATE/new_device_support.yaml @@ -0,0 +1,54 @@ +name: New device support request +description: Request support for a new device +title: "[New device support]: " +labels: [new device support] +body: + - type: markdown + attributes: + value: | + **IMPORTANT:** Before submitting: + - Make sure this device is not already supported in the [dev branch](https://www.zigbee2mqtt.io/advanced/more/switch-to-dev-branch.html) + - Follow this [guide](https://www.zigbee2mqtt.io/advanced/support-new-devices/01_support_new_devices.html) + - If you are using the Home Assistant addon and are still on 1.18.1, check the first point of [this](https://github.com/Koenkk/zigbee2mqtt/releases/tag/1.19.0) + - type: input + id: link + attributes: + label: Link + description: Link of this device (product page) + placeholder: https://www.linktomydevice.org + validations: + required: true + - type: input + id: database + attributes: + label: Database entry + description: Entry of this device in `data/database.db` after pairing it + placeholder: '{"id":53,"type":"Router","ieeeAddr":"0x10458d00024284f69","nwkAddr":10148,"manufId":4151,"manufName":"LUMI","powerSource":"DC Source","modelId":"lumi.relay.c2acn01","epList":[1,2],"endpoints":{"1":{"profId":260,"epId":1,"devId":257,"inClusterList":[0,3,4,5,1,2,10,6,16,2820,12],"outClusterList":[25,10],"clusters":{"genBasic":{"attributes":{"modelId":"lumi.relay.c2acn01","appVersion":1,"manufacturerName":"LUMI","powerSource":4,"zclVersion":0,"stackVersion":2,"hwVersion":18,"dateCode":"8-6-2020"}},"genAnalogInput":{"attributes":{"presentValue":129.04425048828125}},"genOnOff":{"attributes":{"61440":117440715,"onOff":1}}},"binds":[],"configuredReportings":[],"meta":{}},"2":{"profId":260,"epId":2,"devId":257,"inClusterList":[6,16,4,5],"outClusterList":[],"clusters":{"genOnOff":{"attributes":{"61440":237478966,"onOff":0}}},"binds":[],"configuredReportings":[],"meta":{}}},"appVersion":1,"stackVersion":2,"hwVersion":18,"dateCode":"8-6-2020","zclVersion":0,"interviewCompleted":true,"meta":{},"lastSeen":1640285631405}' + validations: + required: true + - type: textarea + id: notes + attributes: + label: Comments + placeholder: I tried to follow the supporting new device page but got stuck at... + validations: + required: true + - type: textarea + attributes: + label: External converter + description: In case you tried to create an external converter, put it below + render: shell + - type: markdown + attributes: + value: | + # Lights + In case this device is a light, fill in the fields below: + - type: input + attributes: + label: Supported color modes + placeholder: color temperature, color (rgb) + - type: input + attributes: + label: Color temperature range + description: In case this light supports color temperature, provide the color temperature range. [How to do this](https://www.zigbee2mqtt.io/advanced/support-new-devices/01_support_new_devices.html#_3-1-retrieving-color-temperature-range-only-required-for-lights-which-support-color-temperature). This currently requires the latest [dev branch](https://www.zigbee2mqtt.io/advanced/more/switch-to-dev-branch.html). + placeholder: '{"colorTempPhysicalMin":153,"colorTempPhysicalMax":454}' \ No newline at end of file diff --git a/.github/ISSUE_TEMPLATE/problem_report.md b/.github/ISSUE_TEMPLATE/problem_report.md deleted file mode 100644 index 55b96bd1f..000000000 --- a/.github/ISSUE_TEMPLATE/problem_report.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -name: Problem report -about: Create a report to help us improve -title: '' -labels: problem -assignees: '' - ---- - - - - - -## What happened - -## What did you expect to happen - -## How to reproduce it (minimal and precise) - -## Debug info -Zigbee2MQTT version: -Adapter hardware: CC2531, CC2530, CC26X2R1, CC1352P-2, Conbee II -Adapter firmware version: diff --git a/.github/ISSUE_TEMPLATE/problem_report.yaml b/.github/ISSUE_TEMPLATE/problem_report.yaml new file mode 100644 index 000000000..0d7b188e3 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/problem_report.yaml @@ -0,0 +1,68 @@ +name: Problem report +description: Create a report to help us improve +title: "[Problem]: " +labels: [problem] +body: + - type: markdown + attributes: + value: | + **IMPORTANT:** Before submitting: + - You read the [FAQ](https://www.zigbee2mqtt.io/guide/faq/) + - Zigbee2MQTT fails to start? Read [this](https://www.zigbee2mqtt.io/guide/installation/20_zigbee2mqtt-fails-to-start.html) + - Make sure the bug also occurs in the [dev branch](https://www.zigbee2mqtt.io/advanced/more/switch-to-dev-branch.html) + - Make sure you are using the [latest firmware](https://www.zigbee2mqtt.io/guide/adapters/#recommended) on your adapter + - The issue has not been [reported already](https://github.com/Koenkk/zigbee2mqtt/issues) + - Is your issue related to the fronted? Then click [here](https://github.com/nurikk/zigbee2mqtt-frontend/issues/new?assignees=&labels=bug%2Ctriage&template=bug_report.yaml&title=%5BBug%5D%3A+) + - If you are using the Home Assistant addon and are still on 1.18.1, check the first point of [this](https://github.com/Koenkk/zigbee2mqtt/releases/tag/1.19.0) + - type: textarea + id: what_happend + attributes: + label: What happened? + validations: + required: true + - type: textarea + id: expect_to_happen + attributes: + label: What did you expect to happen? + placeholder: I expected that ... + validations: + required: true + - type: textarea + id: reproduce + attributes: + label: How to reproduce it (minimal and precise) + placeholder: First do this, than this.. + validations: + required: true + - type: input + id: z2m_version + attributes: + label: Zigbee2MQTT version + description: Can be found in the frontend -> settings -> about -> Zigbee2MQTT version + placeholder: '1.22.1' + validations: + required: true + - type: input + id: adapter_fwversion + attributes: + label: Adapter firmware version + description: Can be found in the frontend -> settings -> about -> coordinator revision + placeholder: '20211210' + validations: + required: true + - type: input + id: adapter + attributes: + label: Adapter + description: The adapter you are using + placeholder: Electrolama zig-a-zig-ah! (zzh!), Slaesh's CC2652RB stick, ... + validations: + required: true + - type: textarea + id: log + attributes: + label: Debug log + description: After enabling [debug logging](https://www.zigbee2mqtt.io/guide/usage/debug.html) the log can be found under `data/log`. Attach the file below + placeholder: Click here and drag the file into it or click on "Attach files by.." below + validations: + required: true \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6fd327d91..613a4a0c0 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,5 +4,5 @@ Everybody is invited and welcome to contribute to Zigbee2MQTT. Zigbee2MQTT is wr - Pull requests are always created against the [**dev**](https://github.com/Koenkk/zigbee2mqtt/tree/dev) branch. - Easiest way to start developing Zigbee2MQTT is by setting up a development environment (aka bare-metal installation). You can follow this [guide](https://www.zigbee2mqtt.io/guide/installation/01_linux.html) to do this. -- You can run the tests locally by executing `npm test`. Zigbee2MQTT enforces 100% code coverage, in case you add new code check if you code is covered by running `npm run test-with-coverage`. The coverage report can be found under `coverage/lcov-report/index.html`. Linting is also enforced and can be run with `npm run eslint`. +- You can run the tests locally by executing `npm test`. Zigbee2MQTT enforces 100% code coverage, in case you add new code check if your code is covered by running `npm run test-with-coverage`. The coverage report can be found under `coverage/lcov-report/index.html`. Linting is also enforced and can be run with `npm run eslint`. - When you want to add support for a new devices no changes to Zigbee2MQTT have to be made, only to zigbee-herdsman-converters. You can find a guide for it [here](https://www.zigbee2mqtt.io/advanced/support-new-devices/01_support_new_devices.html). diff --git a/README.md b/README.md index 23dc214ee..6ece6eb46 100644 --- a/README.md +++ b/README.md @@ -67,7 +67,7 @@ Zigbee2MQTT integrates well with (almost) every home automation solution because ![Architecture](images/architecture.png) ### Internal Architecture -Zigbee2MQTT is made up of three modules, each developed in its own Github project. Starting from the hardware (adapter) and moving up; [zigbee-herdsman](https://github.com/koenkk/zigbee-herdsman) connects to your Zigbee adapter and makes an API available to the higher levels of the stack. For e.g. Texas Instruments hardware, zigbee-herdsman uses the [TI zStack monitoring and test API](https://github.com/koenkk/zigbee-herdsman/raw/master/docs/Z-Stack%20Monitor%20and%20Test%20API.pdf) to communicate with the adapter. Zigbee-herdsman handles the core Zigbee communication. The module [zigbee-herdsman-converters](https://github.com/koenkk/zigbee-herdsman-converters) handles the mapping from individual device models to the Zigbee clusters they support. [Zigbee clusters](https://github.com/Koenkk/zigbee-herdsman/blob/master/docs/07-5123-08-Zigbee-Cluster-Library.pdf) are the layers of the Zigbee protocol on top of the base protocol that define things like how lights, sensors and switches talk to each other over the Zigbee network. Finally, the Zigbee2MQTT module drives zigbee-herdsman and maps the zigbee messages to MQTT messages. Zigbee2MQTT also keeps track of the state of the system. It uses a `database.db` file to store this state; a text file with a JSON database of connected devices and their capabilities. +Zigbee2MQTT is made up of three modules, each developed in its own Github project. Starting from the hardware (adapter) and moving up; [zigbee-herdsman](https://github.com/koenkk/zigbee-herdsman) connects to your Zigbee adapter and makes an API available to the higher levels of the stack. For e.g. Texas Instruments hardware, zigbee-herdsman uses the [TI zStack monitoring and test API](https://github.com/koenkk/zigbee-herdsman/raw/master/docs/Z-Stack%20Monitor%20and%20Test%20API.pdf) to communicate with the adapter. Zigbee-herdsman handles the core Zigbee communication. The module [zigbee-herdsman-converters](https://github.com/koenkk/zigbee-herdsman-converters) handles the mapping from individual device models to the Zigbee clusters they support. [Zigbee clusters](https://github.com/Koenkk/zigbee-herdsman/blob/master/docs/07-5123-08-Zigbee-Cluster-Library.pdf) are the layers of the Zigbee protocol on top of the base protocol that define things like how lights, sensors and switches talk to each other over the Zigbee network. Finally, the Zigbee2MQTT module drives zigbee-herdsman and maps the zigbee messages to MQTT messages. Zigbee2MQTT also keeps track of the state of the system. It uses a `database.db` file to store this state; a text file with a JSON database of connected devices and their capabilities. Zigbee2MQTT provides a [web-based interface](https://github.com/nurikk/zigbee2mqtt-frontend) that allows monitoring and configuration. ### Developing Zigbee2MQTT uses TypeScript (partially for now). Therefore after making changes to files in the `lib/` directory you need to recompile Zigbee2MQTT. This can be done by executing `npm run build`. For faster development instead of running `npm run build` you can run `npm run build-watch` in another terminal session, this will recompile as you change files.