MQTT action mapping observed for smartdevices vs chargingstations endpoints

[myny-git]

Purpose

This note documents observed MQTT actions after triggering charging-related actions through either:

1. the official Smappee app, or
2. the public Smappee REST API.

The goal is to record the observed behaviour as accurately as possible, without assuming that REST API endpoint names and MQTT action names map one-to-one.

Sensitive values such as bearer tokens, service location IDs, smart device UUIDs and charging station IDs are replaced by placeholders.

The main reason for this are the sometimes buggy api-calls (#103 #156 etc)

---

Experimental setup

MQTT traffic was monitored while triggering charging actions through the Smappee app and through REST API calls.

The REST API calls used the following endpoint families:

/dev/v3/servicelocation/{service_location_id}/smartdevices/{smart_device_uuid}/actions/...

and:

/dev/v3/chargingstations/{charging_station_id}/connectors/{connector_id}/mode

The observed MQTT actions were then compared with the action that was triggered.

---

Observations

1. Smappee app mode button: Standard

Trigger

Clicked Standard in the official Smappee app.

Observed MQTT action

setchargingmode = {"mode":"STANDARD"}

---

2. Smappee app mode button: Smart

Trigger

Clicked Smart in the official Smappee app.

Observed MQTT action

setchargingmode = {"mode":"SMART"}

---

3. Smappee app mode button: Solar

Trigger

Clicked Solar in the official Smappee app.

Observed MQTT action

setchargingmode = {"mode":"SOLAR"}

---

4. Smappee app: Pause charging followed by Resume charging

Trigger

1. Pressed Pause charging in the official Smappee app.
2. Then pressed Resume charging in the official Smappee app.
   (only available in STANDARD mode)

Observed MQTT actions

pausecharging = {}
setchargingmode = {"mode":"STANDARD"}

Note

No separate resumecharging MQTT action was observed in this test. setchargingmode seems to do the resume charging.

---

5. Smartdevices endpoint: setChargingMode with STANDARD

REST call

curl -X POST "https://app1pub.smappee.net/dev/v3/servicelocation/{service_location_id}/smartdevices/{smart_device_uuid}/actions/setChargingMode" \
  -H "Authorization: Bearer XXX" \
  -H "Content-Type: application/json" \
  -d '[{"spec":{"name":"mode","species":"String"},"value":"STANDARD"}]'

Observed MQTT action

setchargingmode = {"mode":"STANDARD"}

---

6. Smartdevices endpoint: setChargingMode with SMART

REST call

curl -X POST "https://app1pub.smappee.net/dev/v3/servicelocation/{service_location_id}/smartdevices/{smart_device_uuid}/actions/setChargingMode" \
  -H "Authorization: Bearer XXX" \
  -H "Content-Type: application/json" \
  -d '[{"spec":{"name":"mode","species":"String"},"value":"SMART"}]'

Observed MQTT action

setchargingmode = {"mode":"SMART"}

---

7. Smartdevices endpoint: setChargingMode with SOLAR

REST call

curl -X POST "https://app1pub.smappee.net/dev/v3/servicelocation/{service_location_id}/smartdevices/{smart_device_uuid}/actions/setChargingMode" \
  -H "Authorization: Bearer XXX" \
  -H "Content-Type: application/json" \
  -d '[{"spec":{"name":"mode","species":"String"},"value":"SOLAR"}]'

Observed MQTT action

setchargingmode = {"mode":"SOLAR"}

---

8. Smartdevices endpoint: pauseCharging

REST call

curl -X POST "https://app1pub.smappee.net/dev/v3/servicelocation/{service_location_id}/smartdevices/{smart_device_uuid}/actions/pauseCharging" \
  -H "Authorization: Bearer XXX" \
  -H "Content-Type: application/json"

Observed MQTT action

pausecharging = {}

---

9. Smartdevices endpoint: normalChargingMode

REST call

curl -X POST "https://app1pub.smappee.net/dev/v3/servicelocation/{service_location_id}/smartdevices/{smart_device_uuid}/actions/normalChargingMode" \
  -H "Authorization: Bearer XXX" \
  -H "Content-Type: application/json"

Observed MQTT action

normalchargingmode = {}

---

10. Smartdevices endpoint: smartChargingMode

REST call

curl -X POST "https://app1pub.smappee.net/dev/v3/servicelocation/{service_location_id}/smartdevices/{smart_device_uuid}/actions/smartChargingMode" \
  -H "Authorization: Bearer XXX" \
  -H "Content-Type: application/json"

Observed MQTT action

smartchargingmode = {}

---

11. Smartdevices endpoint: setPercentageLimit

REST call

curl -X POST "https://app1pub.smappee.net/dev/v3/servicelocation/{service_location_id}/smartdevices/{smart_device_uuid}/actions/setPercentageLimit" \
  -H "Authorization: Bearer XXX" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "spec": {
        "name": "percentageLimit",
        "species": "Integer"
      },
      "value": 10
    }
  ]'

Observed MQTT action

setpercentagelimit = {"percentageLimit":10}

Note

This looks similar to the MQTT action observed when using the max charging speed slider in the Smappee app.

---

12. Chargingstations endpoint: connector mode NORMAL

REST call

curl -X PUT "https://app1pub.smappee.net/dev/v3/chargingstations/{charging_station_id}/connectors/1/mode" \
  -H "Authorization: Bearer XXX" \
  -H "Content-Type: application/json" \
  -d '{"mode":"NORMAL"}'

Observed MQTT action

normalchargingmode = {}

---

13. Chargingstations endpoint: connector mode SMART

REST call

curl -X PUT "https://app1pub.smappee.net/dev/v3/chargingstations/{charging_station_id}/connectors/1/mode" \
  -H "Authorization: Bearer XXX" \
  -H "Content-Type: application/json" \
  -d '{"mode":"SMART"}'

Observed MQTT action

smartchargingmode = {}

---

14. Chargingstations endpoint: connector mode PAUSED

REST call

curl -X PUT "https://app1pub.smappee.net/dev/v3/chargingstations/{charging_station_id}/connectors/1/mode" \
  -H "Authorization: Bearer XXX" \
  -H "Content-Type: application/json" \
  -d '{"mode":"PAUSED"}'

Observed MQTT action

pausecharging = {}

---

15. Chargingstations endpoint: connector mode NORMAL with ampere limit

REST call

curl -X PUT "https://app1pub.smappee.net/dev/v3/chargingstations/{charging_station_id}/connectors/1/mode" \
  -H "Authorization: Bearer XXX" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "NORMAL",
    "limit": {
      "unit": "AMPERE",
      "value": 7
    }
  }'

Observed MQTT actions

setpercentagelimit = {"percentageLimit":4}
normalchargingmode = {}

Note

The REST call used an ampere limit, while the observed MQTT action reported a percentage limit.

This REST call also resulted in two MQTT actions being observed.

---

16. Smartdevices endpoint: startCharging without body

REST call

curl -X POST "https://app1pub.smappee.net/dev/v3/servicelocation/{service_location_id}/smartdevices/{smart_device_uuid}/actions/startCharging" \
  -H "Authorization: Bearer XXX" \
  -H "Content-Type: application/json"

Observed MQTT action

startcharging = {"percentageLimit":100}

Note

In this observation, the charger seemed to remain in the current selected mode (STANDARD, SMART or SOLAR).

---

17. Smartdevices endpoint: startCharging with percentageLimit = 5

REST call

curl -X POST "https://app1pub.smappee.net/dev/v3/servicelocation/{service_location_id}/smartdevices/{smart_device_uuid}/actions/startCharging" \
  -H "Authorization: Bearer XXX" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "spec": {
        "name": "percentageLimit",
        "species": "Integer"
      },
      "value": 5
    }
  ]'

Test condition

The charger was in STANDARD mode.

Observed MQTT action

startcharging = {"percentageLimit":100}

Additional observation

Although the MQTT action reported percentageLimit = 100, the Smappee app slider moved to 5%.

This may indicate that the app, API response path and MQTT action do not report the same limit value in this case.

---

18. Smartdevices endpoint: stopCharging

REST call

curl -X POST "https://app1pub.smappee.net/dev/v3/servicelocation/{service_location_id}/smartdevices/{smart_device_uuid}/actions/stopCharging" \
  -H "Authorization: Bearer XXX" \
  -H "Content-Type: application/json"

Observed MQTT action

stopcharging = {}

Additional observation

This ended the charging session in this test.

Afterwards, charging could be started again using either startCharging or setChargingMode.

---

Summary of observed mappings

Trigger source	Triggered action	Observed MQTT action
Smappee app	Standard button	setchargingmode = {"mode":"STANDARD"}
Smappee app	Smart button	setchargingmode = {"mode":"SMART"}
Smappee app	Solar button	setchargingmode = {"mode":"SOLAR"}
Smappee app	Pause charging	pausecharging = {}
Smappee app	Resume charging after pause	setchargingmode = {"mode":"STANDARD"}
smartdevices endpoint	setChargingMode with STANDARD	setchargingmode = {"mode":"STANDARD"}
smartdevices endpoint	setChargingMode with SMART	setchargingmode = {"mode":"SMART"}
smartdevices endpoint	setChargingMode with SOLAR	setchargingmode = {"mode":"SOLAR"}
smartdevices endpoint	pauseCharging	pausecharging = {}
smartdevices endpoint	normalChargingMode	normalchargingmode = {}
smartdevices endpoint	smartChargingMode	smartchargingmode = {}
smartdevices endpoint	setPercentageLimit	setpercentagelimit = {"percentageLimit":10}
smartdevices endpoint	startCharging without body	startcharging = {"percentageLimit":100}
smartdevices endpoint	startCharging with percentageLimit = 5	startcharging = {"percentageLimit":100}; app slider moved to 5%
smartdevices endpoint	stopCharging	stopcharging = {}
chargingstations endpoint	connector mode NORMAL	normalchargingmode = {}
chargingstations endpoint	connector mode SMART	smartchargingmode = {}
chargingstations endpoint	connector mode PAUSED	pausecharging = {}
chargingstations endpoint	connector mode NORMAL with ampere limit	setpercentagelimit = {"percentageLimit":4} and normalchargingmode = {}

---

Preliminary observations

1. App mode buttons consistently use setchargingmode

The official Smappee app mode buttons produced the following MQTT actions:

STANDARD -> setchargingmode = {"mode":"STANDARD"}
SMART    -> setchargingmode = {"mode":"SMART"}
SOLAR    -> setchargingmode = {"mode":"SOLAR"}

In these observations, the app mode buttons did not produce normalchargingmode = {} or smartchargingmode = {} directly.

---

2. The smartdevices setChargingMode endpoint matches the app mode MQTT actions

The smartdevices setChargingMode endpoint produced the same type of MQTT action as the app mode buttons:

setChargingMode STANDARD -> setchargingmode = {"mode":"STANDARD"}
setChargingMode SMART    -> setchargingmode = {"mode":"SMART"}
setChargingMode SOLAR    -> setchargingmode = {"mode":"SOLAR"}

---

3. The chargingstations connector mode endpoint produces different MQTT actions

The chargingstations connector mode endpoint produced different MQTT actions:

NORMAL -> normalchargingmode = {}
SMART  -> smartchargingmode = {}
PAUSED -> pausecharging = {}

These differ from the app mode button observations, even when the resulting user-visible mode may be related.

---

4. Pause appears as pausecharging

Both the app pause action and the tested REST pause actions resulted in:

pausecharging = {}

---

5. Resume was observed as setchargingmode

In the app test, after pausing and then resuming, the observed MQTT actions were:

pausecharging = {}
setchargingmode = {"mode":"STANDARD"}

No separate resumecharging MQTT action was observed in this test.

---

6. Ampere limits may appear as percentage limits on MQTT

When using the chargingstations endpoint with:

{
  "mode": "NORMAL",
  "limit": {
    "unit": "AMPERE",
    "value": 7
  }
}

the MQTT stream showed:

setpercentagelimit = {"percentageLimit":4}
normalchargingmode = {}

So the MQTT stream did not directly report the ampere value from the REST call in this observation.

---

7. One REST call may result in multiple MQTT actions

The NORMAL with ampere limit call produced two MQTT actions:

setpercentagelimit = {"percentageLimit":4}
normalchargingmode = {}

This indicates that MQTT observations should not assume one REST call always produces exactly one MQTT action.

---

8. startCharging may report percentageLimit = 100 on MQTT

The startCharging action without a request body produced:

startcharging = {"percentageLimit":100}

In this observation, the selected charging mode appeared to remain unchanged.

---

9. startCharging with a percentage limit showed different app and MQTT observations

When calling startCharging with percentageLimit = 5 while in STANDARD mode, the observed MQTT action was:

startcharging = {"percentageLimit":100}

However, the Smappee app slider moved to 5%.

This suggests that, at least in this observation, the MQTT action did not directly reflect the slider value shown in the app.

---

10. stopCharging appears as stopcharging and ended the session

The stopCharging action produced:

stopcharging = {}

In this observation, it ended the charging session. Charging could afterwards be started again using either startCharging or setChargingMode.