RESTful sensor, modern syntax?

Configuration
1

So I am attempting to understand template entities but find the documentation utterly confusing. There seems to have been a somewhat recent shift to “modern configuration”, with what is now referred to as “legacy configuration” “no longer recommended”.

The sensors I’d like to create are dependent on fetching data from the web. There is a RESTful Sensor integration which looks like a suitable tool for the task. All of that integration’s documentation however is clearly written for the “legacy” configuration.

It is not at all obvious to me how to adapt a RESTful sensor to the modern configuration. Is it even possible? If not, how do I fetch data and use it to update a set of attributes in a modern configuration?

I would eventually like to turn these sensors inte template blueprints, which obviously would not be possible with the legacy syntax. I did find another RESTful Command integration, but that seems to require extensive setup in configuration.yaml and thus wouldn’t work for a blueprint that ideally should be more or less self-contained.

Another confusing thing about “modern” configuration though are some keywords. The documentation says to use the keys trigger, condition and action. Very recently though automations/scripts changed their syntax to use triggers, conditions and actions. Why does template entities not support the same syntax? Or do they but the documentation is just lagging behind?

2

Let’s see if this helps. In my configuration.yaml file I have the following line:

rest: !include rest.yaml

Then in rest.yaml I have, for example:

- resource: http://172.16.1.4/status.json
  sensor:
    - name: HDHomerun Tuner 1
      json_attributes_path: "$..[?(@.Resource=='tuner0')]"
      json_attributes:
        - Resource
        - VctNumber
        - VctName
        - Frequency
        - SignalStrengthPercent
        - SignalQualityPercent
        - SymbolQualityPercent
        - NetworkRate
        - TargetIP
      icon: mdi:numeric-1-box
      value_template:  >-
        {% if value_json[0].VctName is defined %}
          In Use
        {% else %}
          Idle
        {% endif %}
- resource: http://172.16.1.4/discover.json
  sensor:
    name: HDHomerun Info
    json_attributes:
      - FriendlyName
      - ModelNumber
      - FirmwareName
      - FirmwareVersion
      - DeviceID
      - DeviceAuth
      - UpgradeAvailable
      - BaseURL
      - LineupURL
      - TunerCount
      - ConditionalAccess
    value_template:  >-
      {% if value_json.UpgradeAvailable is defined %}
        Upgrade Available
      {% else %}
        OK
      {% endif %}

These two get the status of my SiliconDust tuner (well, tuner 1 anyway) plus some info on the HDHomeRun.

I don’t know how much that answers your question, but at least it’s a couple working examples. Also, the REStful Sensor integration is done by adding stuff to your configuration.yaml file (just like the RESTful Command integration). I don’t do blueprinting work, so I don’t know what that means for what you’re trying to do.

2 Likes
3

Alright, thanks, that does clear things up somewhat.

So what in the “legacy” configuration is expressed as…

sensor:
  - platform: rest
    resource: …
    …

…would translated to “modern” configuration look like:

rest:
  - resource: …
    sensor:
      - …

The problem for me though is that rest: header, which I would guess probably does not support blueprints. They were just recently introduced for template: entities and barely work as it is unfortunately.

What I still don’t quite understand about the RESTful Sensor is how to set the state and attributes. The data I am fetching is unfortunately neither JSON nor XML, but raw HTML which will require some filtering to get at the values I want.

As I understand it value_template is only applicable for the entity state? The only way to set additional attributes is through json_attributes, but that seems to only work if the incoming data is already JSON or XML?

4

Re-reading the template entities documentation again, it looks like anything in the action section that is fed into a response_variable will be available in the sensor section. That would sure help my use case!

However, I still have no idea how to actually fetch the data in a blueprintable way. Are there any alternatives to the RESTful Command integration which works in a similar way, but lets you specify all parameters in the data section of the action rather than forcing setup in configuration.yaml?

5

For this project I think I have abandoned the idea of using sensors at all and going for a traditional automation only.

I did manage to figure out how to return any desired values from the actions of a modern configuration sensor though, so if anyone finds this thread in the future this is how:

template:
- action:
  - variables:
      demo_response:
        demo_state: Test 123
        demo_attribute: Testing testing testing
  - stop:
    response_variable: demo_response
  sensor:
    state: "{{ demo_response.demo_state }}"
    attributes:
      demo: "{{ demo_response.demo_attribute }}"

As above, end your actions with stop and set response_variable to the name of one of your variables (which must be a mapping/dict). An example of this probably should be added to the documentation. Slightly confusing to use the same syntax I must say, when for stop the response variable will become an output, whereas for other actions it is more of an input.

Also, yes the syntax overall currently still must be action / trigger / condition. Think I will eventually attempt to submit a patch which changes the defaults to actions / triggers / conditions just like the updates automation/script syntax.

6

You are misreading the two options for REST. You can:

  • create individual sensors with the REST platform:
sensor:
  - platform: rest
  • or create a number of sensors under the REST integration:
rest:
  - resource: URL
    sensor:

These are not legacy and modern versions — they are two distinct methods. They’re also not related to the template sensors.

7

What even is a platform? I must admit I have absolutely no idea as HASS terminology is maddeningly confusing sometimes, with seemingly the same words used for entirely different things all of the time . In automation syntax, platform was just recently renamed to trigger. But that appears to be completely unrelated?

This makes some things make less sense for me though. My assumption was kind of that a template entity simply was any and all sensors defined in configuration.yaml, and the legacy/modern configuration transition was to make any sensor blueprintable. But then this means that the amount of blueprintable sensors is much, much smaller than I expected and will not apply to REST sensors and whatever other dozens types of sensors there are. How… disappointing.

8

It’s all about where they get their input.

A template sensor solely uses a Jinja template, the code in {{ }} to generate its state.

A REST sensor, whether as a sensor platform or via the integration (text at the start of that link doesn’t help!), uses a network response (text, JSON, XML) as its input, although it can then use a template to manipulate that input further.

I think of platforms and integrations as different hierarchy levels in the codebase. There’s a general-purpose sensor integration that supports a lot of platforms. The legacy template platform is one of those.

However, in order to support more entities, and probably for neater, more manageable code, template has become its own integration, supporting sensors, switches and many more — even template weather entities.

The current position of modern and legacy template sensors is a side-effect of this evolution. The ideal from the point of view of neatness would be to drop the legacy support altogether, but that would break many people’s existing configurations.

9

That much I have come to understand. But what is the difference between a platform (in general, and more specifically the REST platform) and an integration (the REST integration)?

10

Edited above, to the best of my understanding. Also see the developer docs:

11

I am not sure if that makes me more or less confused to be honest :stuck_out_tongue:

The page you linked to is part of the developer documentation. Unless there is some nuance I am missing, what it calls integration platforms is in the user documentation generally described as a building block integration (see for example Light). Are they the exact same thing and one of the two is out of date with the latest terminology, or are the differing terms intentional?

Either way, it doesn’t quite makes sense to me why REST would be an integration platform. I don’t see how it would qualify as a platform on which to build other integrations in the same way as say a Light.

And again, my previous assumption for why template entities switched to modern configuration was for the sake of easier blueprinting. But from that perspective, the legacy configuration syntax would’ve made much more sense. Rather than calling them template entity blueprints, they simply could’ve been entity blueprints and applicable to any manually configured entity.

A generalized blueprint parser would render the base configuration and then send the result to the integration for verification/execution. With the chosen modern configuration syntax, it seems like any integration that wanted to support blueprints would have to reinvent/reimplement the wheel independently.

But I guess template entity blueprints could potentially be enough, if every way a sensor could intake data were also possible to accomplish with an action. But right now it isn’t, at least not without first doing things like manually setting up a RESTful Command in configuration.yaml. Sigh…