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.

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

chore: repo &README improvements #45

Merged
merged 5 commits into from
Apr 15, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
2 changes: 0 additions & 2 deletions .github/workflows/example_build.yml
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,6 @@ name: Prepared SDK env

on:
workflow_dispatch:
release:
types: [published]

concurrency:
group: ${{ github.workflow }}-${{ github.head_ref }}
Expand Down
4 changes: 2 additions & 2 deletions .github/workflows/go.yml
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,6 @@ jobs:
uses: actions/setup-go@v5
with:
go-version: '1.21'
cache-dependency-path: cli/go.sum
cache-dependency-path: go.sum
- name: Test
run: cd cli && go test ./...
run: go test ./...
2 changes: 1 addition & 1 deletion .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
*~

# build
base/build
base
.vscode/
.venv/
vendor
Expand Down
98 changes: 5 additions & 93 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,98 +15,6 @@ Priorities can be ordered as:
* Adding known sensors
* Adding Zigbee clusters & templates for unavailable clusters in ZBOSS

### Source Generation
CLI can generate source, which can then be built and flashed.

"Source" includes C source code, app config(`proj.conf`) and overlay (`app.overlay`).

### Building
Assuming configuration file is located at `./zigbee_test.yml` and directory for generated & built firmware should be `./firmware` the command to generate & build the firmware will be:
```sh
go run ./cli/cmd/zigbee --config ./zigbee_test.yml firmware --workdir ./firmware build
```

Only source code can be generated by adding `--only-generate` flag after `build`:
```sh
go run ./cli/cmd/zigbee --config ./zigbee_test.yml firmware --workdir ./firmware build --only-generate
```

Note: `build` command will not clear the work directory, so if it already contains some additional files they may be used while building the firmware.

This also applies when removing features from configuration and re-building the firmware: some files might be left after feature that requires it was removed.
It could lead to a build that is failing.

### Flashing
CLI can flash already built application with a couple of methods:
- nrfutil
- mcuboot
- west
- adafruit (if available in current PATH)

Device already has to be in a mode that will allow flashing(DFU, for example).

Example:
```sh
go run ./cli/cmd/zigbee --config ./zigbee_test.yml firmware --workdir ./firmware flash
```

### Supported devices

This project is being developed based on [nRF52840 Dongle](https://www.nordicsemi.com/Products/Development-hardware/nrf52840-dongle) from [Nordic Semiconductors](https://www.nordicsemi.com/)

Initial goal of the project is to support nRF52840 based devices, with expansion to nRF53 series.

* nRF52840 Dongle
* Arduino Nano 33 BLE (Sense). Probably also other Bossac bootloader devices on nrf52840 as well.
* Support for boards with Adafruit bootloader. Please read note below.

Support is provided for Adafruit bootloader, but is not comprehensevily tested.
This means that any device running Adafruit bootloader will run the firmware generated by this tool,
but it cannot be fully guaranteed that the firmware will work properly on the device in all conditions.

Support was tested on my two boards with Adafruit bootloader(Arduino Nano 33 BLE & Seeed Xiao), and simple firmware was working correctly.

For Adafruit bootloader a UF2 file will be generated, which then can be flashed normally through drag-and-drop.

User can change configuration that allows bootloader support in `cli/types/board/known_boards.go`.


## Using in Home Assistant
[ZHA](https://www.home-assistant.io/integrations/zha/) integration can figure out device capabilities without pre-defined configuration.

Firmware provided by this project is already working on the Dongle and reporting defined values when connected through ZHA.

[Zigbee2MQTT](https://www.zigbee2mqtt.io/) [recently](https://github.com/Koenkk/zigbee2mqtt/releases/tag/1.35.0) added ability to generate definitions for unknown devices, as ZHA does.
While it may not support all clusters and functionalities yet, there is active work going on to make support better.

## CLI

Go CLI application available in `/cli` will provide
necessary options to build and upload firmware based on provided configuration.

For this to work user would need to already have nRF Connect SDK set up, with `west` and probably some flash tool applications available and working.

Defined flash tools are:
* `nrfutil` - already working
* `adadfruit`
* `mcuboot`
* `west` - already working

Default configuration file called `zigbee.yml` will be loaded
and used to configure.
See bare example in `cli/zigbee.yml`, or original configuration definition
in `cli/config/device.go:Device`.

To flash the board with built firmware run
```sh
go run ./cli/cmd/zigbee firmware --workdir <path_to_project> flash
```

Users can flash built applications with [nRF Connect for Desktop](https://www.nordicsemi.com/Products/Development-tools/nRF-Connect-for-Desktop)
as well, if CLI tool is not suited for some cases.

This project needs nRF Connect SDK version 2.5.0. Other versions are not yet tested.

### Licenses
This project uses information from ZBOSS SDK, license for which can be found in `zboss_license.txt`.

Expand All @@ -117,4 +25,8 @@ This project uses information from ZBOSS SDK, license for which can be found in
* * [Documentation](http://developer.nordicsemi.com/nRF_Connect_SDK/doc/latest)
* [Zephyr project](https://www.zephyrproject.org/)
* [ESPHome](https://esphome.io/)
* [Zigbee Cluster Library](https://csa-iot.org/wp-content/uploads/2022/01/07-5123-08-Zigbee-Cluster-Library-1.pdf)
* [Zigbee Cluster Library](https://csa-iot.org/wp-content/uploads/2022/01/07-5123-08-Zigbee-Cluster-Library-1.pdf)

## Special thanks
* @rsporsche - for donating nRF52840 DK board
* @Hedda - for informational support
23 changes: 0 additions & 23 deletions base/CMakeLists.txt

This file was deleted.

26 changes: 0 additions & 26 deletions base/Kconfig

This file was deleted.

82 changes: 0 additions & 82 deletions base/app.overlay

This file was deleted.

18 changes: 0 additions & 18 deletions base/pm_static.yml

This file was deleted.

75 changes: 0 additions & 75 deletions base/prj.conf

This file was deleted.

Loading