Tidy up the use of the term "timestamp" used throughout HA

Hi there,

I recently had a challenge when trying to convert an input_datetime entity into a sensor with the timestamp device class.

When seeing that my blueprint automation needed a sensor with the timestamp device class, I assumed I could create a sensor and set its state by using the input_datetime timestamp attribute, and was baffled when it didn’t work.

Thankfully @123’s solution on this post worked like a charm:

However it seems I’m not the only one confused by this:

Therefore creating a FR to tidy up the usage of the term “timestamp” in HA core. Would suggest that:

  • The “as_timestamp” filter, and the “timestamp” attribute of the input_datetime integration, be renamed to something like “as_unix_timestamp” and “unix_timestamp” respectively (maintaining backwards compatibility)
  • The “timestamp” device class is renamed to something such as “datetime object” (maintaining backwards compatibility)

BONUS:
Perhaps a “as_timestamp_object” filter, or “as_device_class_timestamp” filter (or if the above suggestion is accepted, an “as_datetime_object” filter), or something similar, that is a shortcut for @123 's solution:
{{ (states('input_datetime.example') | as_datetime | as_local).isoformat() }}

I always thought it odd that the device_class was called “timestamp” instead of “datetime object”.

The timestamp sensor allows for timestamps and datetimes as the output, so I’m not sure what your issue was. But the nomenclature is correct throughout the system.

As for the solution, all you need to do is output a float or a datetime object.

The float (timestamp) will be a time from january 1st 1970 in seconds.

The datetime is just a datetime, both work.

A string, an isoformatted datetime.

So in regards to 123s solution, all these templates will work:

{{ states('sensor.device_class_timestamp') | as_datetime }}
{{ states('sensor.device_class_timestamp') | as_datetime | as_local }}
{{ (states('sensor.device_class_timestamp') | as_datetime).isoformat() }}
{{ (states('sensor.device_class_timestamp') | as_datetime | as_local).isoformat() }}
{{ states('sensor.device_class_timestamp')  | as_timestamp }}

The sensor was originally given a device class when only as_timestamp existed, which is why it was originally named timestamp.

Thanks for your explanation @petro.

I didn’t elaborate on the challenge I was having, but happy to do that here:

  • I had an input_datetime entity created through the input_datetime integration in the Helper UI, allowing me to define a time in a field on my dashboard. For “What do you want to input:”, the entity was set to “Date and time”
  • I have a wake up light alarm automation from a blueprint, that allows the next alarm to be set by a sensor with the timestamp device class
  • I initially tried to create the sensor simply by taking the output of the datetime, so utilising the following code:
template:
    # Create a sensor for the Wake Up Alarm automation to read the input datetime from the dashboard
    sensor:
        name: "Wake Up Alarm"
        unique_id: template_se_alarm_01
        state: "{{ states('input_datetime.wake_up_alarm') }}"
        device_class: timestamp
  • The result of the sensor was “Unknown”
  • After realising this didn’t work, I did a bit of digging into the documentation. Before reading through thoroughly I noticed that input_datetime has a timestamp attribute, and seeing this matched the name of my device class, I tried the following code:
template:
    # Create a sensor for the Wake Up Alarm automation to read the input datetime from the dashboard
    sensor:
        name: "Wake Up Alarm"
        unique_id: template_se_alarm_01
        state: "{{ state_attr('input_datetime.wake_up_alarm', 'timestamp') }}"
        device_class: timestamp
  • After the result of the sensor was still “Unknown”, a closer inspection of the documentation showed me that the timestamp device class actually needs either:
  • date: Date string (ISO 8601)
  • timestamp: Datetime object or timestamp string (ISO 8601)
  • So clearly while the timestamp device class will accept a “timestamp string” it’s a bit tricky to work out how such a timestamp string should be formatted, as the following templates fail:


  • Nevertheless while this still isn’t clear to me, I could get the timestamp device class sensor working by providing it with a datetime, per @123’s solution: {{ (states('input_datetime.wake_up_alarm') | as_datetime | as_local).isoformat() }}

I realised my “BONUS” filter was also not explained well… especially as I used the wrong entity in my example :man_facepalming:

I’ve now corrected in my post:

@petro with all the above in mind regarding my confusion with the term timestamp… happy to be corrected where I’ve misunderstood the use of the term, and adjust my FR accordingly! Even if it just ends up meaning making some suggested edits to the documentation to make it even clearer.

Perhaps you could enlighten me why the timestamp device class isn’t accepting the two forms of timestamp as a state input, per my screenshots above?

Good shout. It seems that datetime object would be a better description based on the listed accepted inputs for the sensor state.

Incorporated into the FR, thanks!