From d0f1479c9c71003a94b5ad52ed07ef82a4a8159a Mon Sep 17 00:00:00 2001 From: Stephan van Rooij <1292510+svrooij@users.noreply.github.com> Date: Wed, 14 Feb 2024 10:14:18 +0100 Subject: [PATCH] docs: Modified some links --- .github/ISSUE_TEMPLATE/config.yml | 7 +++++++ README.md | 4 ++++ docs/developers.md | 10 ++++++---- docs/index.md | 8 +++----- docs/sonos-communication.md | 14 ++++++-------- 5 files changed, 26 insertions(+), 17 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml index 3ba13e0..16cba5f 100644 --- a/.github/ISSUE_TEMPLATE/config.yml +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -1 +1,8 @@ blank_issues_enabled: false +contact_links: + - name: Questions + url: https://github.com/svrooij/sonos-api-docs/discussions/categories/q-a + about: Please ask and answer questions here. + - name: All discussions + url: https://github.com/svrooij/sonos-api-docs/discussions + about: General discussions about the Sonos API. \ No newline at end of file diff --git a/README.md b/README.md index 9dcb632..c55e5eb 100644 --- a/README.md +++ b/README.md @@ -45,6 +45,10 @@ You can use the generator to generate your own discovery files, but we also have These files together with the documentation file, are combined to a extensive JSON file, that is used as an input for the generator. +## Community + +If you have any [questions](https://github.com/svrooij/sonos-api-docs/discussions/categories/q-a) or you want to [show](https://github.com/svrooij/sonos-api-docs/discussions/categories/show-and-tell) your Sonos integration. Please join us in the [discussions](https://github.com/svrooij/sonos-api-docs/discussions) tab on this repository. + ## Contributors ✨ diff --git a/docs/developers.md b/docs/developers.md index 935770f..cceace1 100644 --- a/docs/developers.md +++ b/docs/developers.md @@ -55,7 +55,7 @@ For example [this part](https://github.com/svrooij/sonos-api-docs/blob/25aad3a3a We build a custom [generator](https://github.com/svrooij/sonos-api-docs/tree/main/generator/sonos-docs) to do several things. -### Discover services from sonos speaker +### Discover services from Sonos speaker You can use the generator to generate [device discovery files]({{ '/#device-discovery-files' | relative_url }}). For each model we generated a discovery json, as available on main page. We generate this file by parsing the device discovery document available at `http://{sonos_ip}:1400/xml/device_description.xml`. Not every model has the same services, but it seems that if a service is available it's the same as all other models that have that service. @@ -74,9 +74,11 @@ npm install ./bin/run services {sonos-ip} ``` +Please help us out occasionally by running this command on your own Sonos speaker and send us the resulting file. This way we can keep the discovery files up to date. This command will automatically update the discovery files in the `data` folder. These files are used as an input for the generator. Having up to date discovery files will help us to keep the documentation up to date. All personal identifiable information is removed from the discovery files. + ### Combine discovery files and documentation -If you changed the [documentation.json](#documentation.json) file or if you added/updated discovery files, you need to combine the two into one file, the **.cache/combined.json** file. +If you changed the [documentation.json](./documentation.json) file or if you added/updated discovery files, you need to combine the two into one file, the **.cache/combined.json** file. This file is the result of the the manual documentation and the device discovery files. This file is almost 8000 lines of json at the moment, which is why it is ignored in git. Being able to inspect this json file should really help in debugging the generator. @@ -101,7 +103,7 @@ npx @svrooij/sonos-docs combine --docsFile=./docs/documentation.json --folder=./ ### Regenerate documentation -Once you generated the **combined.json** file, you can use the generator to (re)generate the [service documentation]({{ '/services' | relative_url }}). This step is mandatory if you changed either the **documentation.json** or if you added/updated one of the discovery files. +Once you generated the **combined.json** file, you can use the generator to (re)generate the [service documentation]({{ '/services' | relative_url }}). This step is mandatory if you changed either the **documentation.json** or if you added/updated one of the discovery files. The resulting files, are **not to be changed manually**, since changes will get lost upon the next generation. @@ -135,7 +137,7 @@ The template.json file gives some basic information about the template, the auth 1. File usage `index`, will use the data from intermediate.json as input to produce **one file**. 2. File usage `service`, will use the data from each service to produce **one file per service**, be sure to use `{snService}` or `{service}` in the **outputFile**. -Be sure to check out the [docs template](https://github.com/svrooij/sonos-api-docs/tree/main/generator/sonos-docs/templates/docs) to get started. Or the [ts template](https://github.com/svrooij/sonos-api-docs/tree/main/generator/sonos-docs/templates/ts), which is used to generate [sonos-ts](https://svrooij.io/node-sonos-ts/). +Be sure to check out the [docs template](https://github.com/svrooij/sonos-api-docs/tree/main/generator/sonos-docs/templates/docs) to get started. Or the [ts template](https://github.com/svrooij/node-sonos-ts/tree/master/.generator/ts), which is used to generate [Sonos typescript](https://sonos-ts.svrooij.io/). ```bash diff --git a/docs/index.md b/docs/index.md index 2ee2067..4011a63 100644 --- a/docs/index.md +++ b/docs/index.md @@ -38,7 +38,7 @@ This file has a [documentation json schema](https://sonos.svrooij.io/schema/docu ### Update documentation -If you change the [documentation](#manual-documentation-file) file or if you did service discovery for a new device. You can update the documentation files with the following commands: +If you change the [documentation](#manually-documented) file or if you did service discovery for a new device. You can update the documentation files with the following commands: ```shell # Go to generation folder @@ -55,7 +55,7 @@ npm run docs ## Generator -You can find the generator [here](https://github.com/svrooij/sonos-api-docs/tree/main/generator/sonos-docs) and use it to generate your own sonos client in your preferred language. +You can find the generator [here](https://github.com/svrooij/sonos-api-docs/tree/main/generator/sonos-docs) and use it to generate your own Sonos client in your preferred language. ### Device discovery files @@ -84,9 +84,7 @@ The template.json also has a [json schema](https://svrooij.io/sonos-api-docs/sch ## Community -[![Join us on Discord][badge_discord]][link_discord] - -If you need help building an app that talks to your sonos speakers, or you want to share some of your findings. [Join us on Discord][link_discord]. +If you have any [questions](https://github.com/svrooij/sonos-api-docs/discussions/categories/q-a) or you want to [show](https://github.com/svrooij/sonos-api-docs/discussions/categories/show-and-tell) your Sonos integration. Please join us in the [discussions](https://github.com/svrooij/sonos-api-docs/discussions) tab on this repository. ## Contributors ✨ diff --git a/docs/sonos-communication.md b/docs/sonos-communication.md index 38ab2df..140ba96 100644 --- a/docs/sonos-communication.md +++ b/docs/sonos-communication.md @@ -21,7 +21,7 @@ Each sonos speaker has [several soap services]({{'services/' | relative_url }}) ## Sonos SOAP remarks - Sonos communicates booleans as `1` for true and `0` for false. This is something to keep in mind if you see **boolean** somewhere. -- Some actions (like [ListAlarms]({{'services/alarm-clock.html#listalarms' | relative_url }})) return encoded xml as string. Before you can read these, you'll have to decode them and then parse them as XML. Libraries like [node-sonos-ts](https://svrooij.io/node-sonos-ts/sonos-device/services/alarm-clock-service.html#listalarms) provide a way that already parses the the output so you don't have to. +- Some actions (like [ListAlarms]({{'services/alarm-clock.html#listalarms' | relative_url }})) return encoded xml as string. Before you can read these, you'll have to decode them and then parse them as XML. Libraries like [node-sonos-ts](https://sonos-ts.svrooij.io/sonos-device/services/alarm-clock-service.html#listalarms) provide a way that already parses the the output so you don't have to. ## SOAP call @@ -33,7 +33,7 @@ In this sample we described the [SetMute]({{ '/services/rendering-control.html#s | ---- | ------ | | IP of speaker | `192.168.0.31` | | [Control endpoint]({{'/services/rendering-control.html#service-data' | relative_url }}) | `/MediaRenderer/RenderingControl/Control` | -| Service type | `urn:schemas-upnp-org:service:RenderingControl:1` +| Service type | `urn:schemas-upnp-org:service:RenderingControl:1` | You can find this information on the page describing one of [many sonos services]({{'/services/' | relative_url }}). @@ -50,7 +50,7 @@ soapaction: "urn:schemas-upnp-org:service:RenderingControl:1#SetMute" Content-Type: text/xml; charset="utf-8" ``` -The body of the request has to be specified as XML. We also added the correct action body for the `SetMute` action. As you see below, booleans are converted to `1` for true and `0` for false. This is just how sonos works. +The body of the request has to be specified as XML. We also added the correct action body for the `SetMute` action. As you see below, booleans are converted to `1` for true and `0` for false. This is just how Sonos works. ```xml @@ -82,15 +82,13 @@ Success message (without output parameters) to above command: Generic error (when deleting an alarm that doesn't exists) body (HTTP status code 500): ```xml - + s:Client UPnPError - + 800 @@ -117,7 +115,7 @@ Apart from the soap services, sonos also has some http endpoints available where ## Auto discovery Each sonos speaker can be discovered by the [SSDP](https://en.wikipedia.org/wiki/Simple_Service_Discovery_Protocol) or **Simple Service Discovery Protocol**. -In short each speaker listens for a `ssdp:discovery` command. +In short each speaker listens for a `ssdp:discovery` command. Which is actually just a simple UDP packet send to port `1900` on multicast address `239.255.255.250` and `255.255.255.255` with the following body: