MQTT topic hierarchy

[tisoft]

Proposed structure for the MQTT topic hierarchy:

• saic
  • email
    • messages (one subtopic for every message, currently stored on the server)
      • messageId
        • messageType
        • title
        • messageTime
        • sender
        • content
        • status (read/unread)
          • set (read/unread/delete)
        • vin
    • vehicles (one subtopic for every vehicle)
      • VIN
        • info
          • brand
          • model
          • year
          • series
          • color
          • lastMessage (read only, to delete use account topic)
            • messageId
            • messageType
            • title
            • messageTime
            • sender
            • content
            • status (read/unread)
        • refresh
          • mode (off, periodic, auto)
            • set (accepts values from above. Additionally force will trigger a single fetch, but keep the
              current mode)
          • lastChargeState
          • lastVehicleState
          • period (only used if in periodic mode)
            • active (period in seconds to query the API, if the car is active, if not set the inActive period is used)
              • set
            • inActive
              • set
        • configuration (subtopic for each entry from the modelConfigurationJsonStr field from the API)
          • code
            • name
            • value
        • location
          • position (GPOS position as JSON object)
          • heading
          • speed
        • drivetrain
          • charging
            • set
          • chargerConnected
          • chargingType (slow/fast)
          • running
          • auxiliaryBatteryVoltage
          • mileage
          • range
          • current
          • voltage
          • power
          • soc
        • climate
          • interiorTemperature
          • exteriorTemperature
          • remoteTemperature (The temperature used in remote preheat commands)
            • set
          • remoteClimateState (off, front, on)
            • set
          • backWindowHeat (off, on)
            • set
        • windows
          • driver
            • set
          • passenger
            • set
          • rearLeft
            • set
          • rearRight
            • set
          • sunRoof
            • set
        • doors
          • locked
            • set
          • driver
          • passenger
          • rearLeft
          • rearRight
          • bonnet
          • boot
        • tyres
          • frontLeftPressure
          • frontLeftPressure
          • rearLeftPressure
          • rearRightPressure
        • lights
          • mainBeam
          • dippedBeam

Topic names in Italic are placeholders for the actual content. E.g. VIN is replaced by the actual VIN from the
vehicle. Not all vehicles support all functionality, so some of the subtopics will not be available for each type of
vehicle.

[tisoft]

Proposal from SAIC-iSmart-API/saic-java-client#14 (comment):

Add a new topic refresh/period/afterShutdown to configure the grace period when the car enters the inactive state. This can be used to detect a starting charge right after the car has been switched off.

[tisoft]

I would propose the name refresh/period/inActiveDelay or refresh/period/inActiveGrace.

[mschmiedel]

I like inActiveGrace, seems to be the one that comes closest to the intention...

[nanomad]

As discussed in another issue, I would suggest a separate topic for the polling rate while during inActiveGrace. having it equal to the active period may cause 12V battery drain if mis-used

[mschmiedel]

I am missing a topic for the chrgngRmngTime from the API. how about /drivetrain/remainingChargeTime?

[mschmiedel]

I would add this feature at some point in the future, would be real helpful to see remaining time...

[mschmiedel]

Added this mr as a draft first: SAIC-iSmart-API/saic-java-client#36

Will be testing it in the following days.

[tisoft]

remoteClimateState is 1 for enabling the blower, without enabling the A/C.

How should we call the new state?

Suggestions:

• blow
• blowing
• blowOnly
• blowingOnly

More suggestions?

[mschmiedel]

I like blowOnly or blowerOnly. However any option that contains "blow" should do the trick to understand that no HVAC is switched on there...

[DreamT80]

I also vote for one of the *Only alternatives. It tells us that it is a subset of the A/C that only runs part of it's functionality.

"blowingOnly" I think is the best alternative. It follows the same convention as "Heating" in "rearWindowDefrosterHeating".

[tisoft]

I will use blowingOnly.

[tisoft]

We have several fields in the API that contain time data. I think we should agree on how to represent them in MQTT values.

Here are the possible formats I can think of:

Timestamps:

• UNIX time 1687085943
• ISO 8601 in UTC 2023-06-18T10:59:03.023Z
• ISO 8601 with offset 20230618T125903.023+0200
• ISO 8601 with offset and timezone 20230618T125903.023+0200[Europe/Berlin]

Durations:

• seconds as integer 90
• minutes as integer 2
• minutes as float 1.5
• ISO 8601 PT1M30S

I'm open for different formats for discussion.

[mschmiedel]

Hi, I will test this out today, hopefully no breaking change... :)

What about the remaining charge time? The actual branch seems to work fine with my car with the actual setup for the last few weeks... Only question is if we keep minutes or want to change to something else...

[mschmiedel]

-> Just tested with HomeAssistant, works like a charm, could completely delete this hack:

value_template: "{{ ((value[:-9] | replace('"', '') | replace('T', ' ') | as_timestamp) + 3600 * now().timetuple().tm_isdst) | timestamp_local }}"

[mschmiedel]

Adding some ideas to the conversation. The refreshPeriod configs and so are in seconds, so handling all durations in seconds seems like the best option for me... What do you think?

[tisoft]

I would also tend to use seconds everywhere. If we ever need millisecond precision, we could use fractions. (But I don't see where we would need that)

[mschmiedel]

Since we released the remainingChargingTime topic, it should be reflected in the topic hierarchy. How about adding this to some path in the documentation project? Would offer to add it there, we should just agree on some format (plain MD or something else?)