-
Notifications
You must be signed in to change notification settings - Fork 1.8k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge branch 'current' into guide_for_noobs
- Loading branch information
Showing
15 changed files
with
173 additions
and
14 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1 +1 @@ | ||
| 2024.10.2 | ||
| 2024.10.3 |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,132 @@ | ||
| json Component | ||
| ============== | ||
|
|
||
| .. seo:: | ||
| :description: Instructions for parsing and building json within ESPHome. | ||
| :keywords: json | ||
|
|
||
| The ``json`` component enables ESPHome to work with JSON data in automations, sensors, and HTTP requests. This is particularly useful for: | ||
|
|
||
| - Processing API responses | ||
| - Sending structured data to external services | ||
| - Parsing configuration from JSON files | ||
|
|
||
| What is JSON? | ||
|
|
||
| JSON is a text syntax that facilitates structured data interchange between all programming languages. JSON | ||
| is a syntax of braces, brackets, colons, and commas that is useful in many contexts, profiles, and applications. | ||
| JSON stands for JavaScript Object Notation and was inspired by the object literals of JavaScript aka | ||
| ECMAScript as defined in the `ECMAScript Language Specification, Third Edition <https://ecma-international.org/wp-content/uploads/ECMA-404_2nd_edition_december_2017.pdf>`_ . | ||
|
|
||
| Example 1: Relatively complex JSON | ||
|
|
||
| .. code-block:: json | ||
| { | ||
| "first_name": "John", | ||
| "last_name": "Smith", | ||
| "is_alive": true, | ||
| "age": 27, | ||
| "address": { | ||
| "street_address": "21 2nd Street", | ||
| "city": "New York", | ||
| "state": "NY", | ||
| "postal_code": "10021-3100" | ||
| }, | ||
| "phone_numbers": [ | ||
| { | ||
| "type": "home", | ||
| "number": "212 555-1234" | ||
| }, | ||
| { | ||
| "type": "office", | ||
| "number": "646 555-4567" | ||
| } | ||
| ], | ||
| "children": [ | ||
| "Catherine", | ||
| "Thomas", | ||
| "Trevor" | ||
| ], | ||
| "spouse": null | ||
| } | ||
| Example 2: Simple JSON: | ||
|
|
||
| .. code-block:: json | ||
| {"key": 42.0, "greeting": "Hello World"} | ||
| Parsing JSON: | ||
| ------------- | ||
|
|
||
| This example assumes that the server returns a response as a JSON object similar to this: | ||
| ``{"status":"play","vol":"42","mute":"0"}`` | ||
|
|
||
|
|
||
| If you want to retrieve the value for the ``vol`` key and assign it to a template ``sensor`` or ``number`` component | ||
| whose ``id`` is set to ``player_volume`` you can do this, but note that checking for the presence of the key will prevent difficult-to-read error messages: | ||
|
|
||
| .. code-block:: yaml | ||
| on_...: | ||
| - http_request.get: | ||
| url: https://esphome.io | ||
| capture_response: true | ||
| on_response: | ||
| then: | ||
| - lambda: |- | ||
| json::parse_json(body, [](JsonObject root) -> bool { | ||
| if (root["vol"]) { | ||
| id(player_volume).publish_state(root["vol"]); | ||
| return true; | ||
| } | ||
| else { | ||
| ESP_LOGD(TAG,"No 'vol' key in this json!"); | ||
| return false; | ||
| } | ||
| }); | ||
| Building JSON: | ||
| -------------- | ||
|
|
||
| You can build JSON in a lambda with a nested array like this: | ||
|
|
||
| .. code-block:: | ||
| on_...: | ||
| - http_request.post: | ||
| url: https://esphome.io | ||
| json: |- | ||
| root["key"] = id(my_sensor).state; | ||
| root["greeting"] = "Hello World"; | ||
| This will send:: | ||
| ``{"key": 42.0, "greeting": "Hello World"}`` | ||
|
|
||
|
|
||
| Troubleshooting Errors: | ||
| ----------------------- | ||
| A very common error when deserializing is: | ||
|
|
||
| .. code-block:: | ||
| JSON parse error: InvalidInput | ||
| The software ESPHome uses does not provide particularly informative messages as to why, but | ||
| the people at ArduinoJson have created a `wonderful troubleshooter <https://arduinojson.org/troubleshooter>`__. | ||
|
|
||
| Another important resource is `JSONLint <https://jsonlint.com/>`__. It will help you determine if the JSON you are using is valid. It must be valid to work with ESPHome's deserializer and it probably needs to be valid for the destination, if you are sending it. | ||
|
|
||
|
|
||
| See Also | ||
| -------- | ||
|
|
||
| - :doc:`index` | ||
| - :apiref:`http_request/http_request.h` | ||
| - :apiref:`json/json_util.h` | ||
| - `ArduinoJson <https://arduinojson.org/>` | ||
| - :ghedit:`Edit` | ||
|
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,4 +1,4 @@ | ||
| sphinx==7.1.2 | ||
| sphinx-autobuild==2021.3.14 | ||
| sphinx-tabs==3.4.5 | ||
| sphinx-tabs==3.4.7 | ||
| sphinx-toolbox==3.8.0 |