Documenting the OCPP Integration

[GrantKeymer]

I've noticed since the recent changes to a separate sensor.charger.status.connector that the original one sensor.charger_status always says 'Available' no matter what. It had me fooled for a while because everything relying on the state of that sensor was broken. My fancy dashboard didn't work and even the automation written by @lbbrhzn didn't work 😕

Then I saw the pull request where the new sensor was mentioned and it seems to work fine.

Should the original sensor be removed to avoid confusion?

[lbbrhzn]

Hi Grant, sorry to break your automations! I probably should have documented this more clearly in the release notes, my apologies. It seems there is a need to document the integration in more detail, for instance in the project's wiki.
Maybe you'd like to volunteer?

According to the OCPP standard there really is more than a single status: one for the main controller of the charger, and one for each connector. Yes, that means there can even be more than two!

Previously there was only a single status entity, resulting in a continuously toggling between several status values for some systems.

To solve that issue I decided to map everything on just two status entities. One for the main status (connector_id=0) and one for the connector statuses (connector_id>0). The state value of the connector status entity reflects connector 1, other connectors are stored in the extra attributes.

There's a similar issue with the power / energy / current / voltage values: there can be different ones, depending on the connector and the transaction.

I'm still trying to figure out how to present this in the UI in a simple way, without creating a plethora of entities. Any suggestions from you side?

[drc38]

We could create a switch entity that controls authorization of a particular tag: _authorization. The first time a new tag is detected authorization will be automatically denied, but you can accept subsequent tries by flipping the switch. I like that better than manually maintaining an authorization list in an options flow. Home assistant already allows the user to give an entity a more meaningful name, so it should not be need to add additional functionality for that.

An actionable notification might work well for authorising dynamically:
https://companion.home-assistant.io/docs/notifications/actionable-notifications/

[GrantKeymer]

Here's what I've found so far regarding the usage of extra_attr...

data_transfer function stores vendor specific data from the charger in the form {message id: data payload}

get_configuration function stores {key: value pairs} for each config key supported by charger

process_phases function stores metering data from charger according to the following sequence:

Name of metric (e.g. Voltage)
Phase (L1, L2, L3)
Value
Unit
Context (Sampled Periodically or according to Clock)

on_status_notification function stores status changes relating to individual connectors in the form {connector_id: status}
Also stores error codes relating to individual connectors in the form {connector_id: error_code}

Other references to extra_attr seem to be retrieving the data rather than storing it.

[GrantKeymer]

At last, I think I've got my head around this now. What we need is to reduce the number of entities and use extra_attr for some of them, to store diagnostic data which won't need to be separately displayed/charted in HA. How about this...

Sensors relating to the entire charger

Stored in entity charger_metrics

voltage (top level variable i.e. chartable directly)
frequency
energy_import_register
energy_meter_start
status

Stored in entity charger_diagnostics

heartbeat (top level variable i.e. chartable directly)
error_code
latency_ping
latency_pong
reconnects
id_tag
timestamp_config_response
timestamp_data_response

Stored in entity charger_info

vendor (top level variable i.e. displayable directly)
model
id
serial
features
status_firmware
version_firmware
connectors

Sensors relating to a particular connector

Stored in connector1_xxx (or connector2_xxx etc) as separate entities

connector1_power_active_import
connector1_power_offered
connector1_current_import
connector1_current_offered
connector1_energy_session
connector1_time_session

Stored in connector1_status (or connector2_status etc)

status (top level variable i.e. displayable directly)
transaction_id
stop_reason
error_code

I've left the first 6 connector-specific entities separate for now because there is often the need to use them for a meter, chart, status indicator etc. If hidden inside extra_attr, it becomes more difficult to do this. However, the last few (status, transaction_id, stop reason and error_code) can sensibly be combined.

Hopefully this will be more what you had in mind.

[drc38]

If we will need to create a template sensor (which is sensor entity) to chart data I assume there is no particular benefit in storing it in extra_attr or is there?

The charger info data makes sense combing into a single metric. Some of the info however already is available in the device registry such as firmware, so do we need this in the metric?

[GrantKeymer]

If we will need to create a template sensor (which is sensor entity) to chart data I assume there is no particular benefit in storing it in extra_attr or is there?

I don't think we need to create a template sensor to chart each of these less important variables. It would be good to provide one as an example, which could be documented in the Wiki. The benefit I see from storing them in extra_attr is that it's very easy to use the dropdown attributes arrow to display the extra variables associated with a given entity. If someone decides they need to chart any particular extra_attr variable, they can create their own template, modelled on the example.

The charger info data makes sense combing into a single metric. Some of the info however already is available in the device registry such as firmware, so do we need this in the metric?

Agreed, we could leave pretty much all charger info contained solely in the registry.

[GrantKeymer]

OK guys, I'm ready to start writing the Wiki whenever you give me the green light. Are we agreed on the above list of sensors + entities as being the best way forward? If not, then let's refine it a bit more until we reach agreement.

After looking for suitable examples of Wikis hosted on Github, I've chosen this one as a good starting point (just the structure not any of the content)...

https://github.com/Netflix/Hystrix/wiki

One of the first sections I want to write, deals with pitfalls best avoided during installation. Basically, things I wish I'd known before installing this integration for the first time. To help me along the way, I need your comments on this issue...

When you add the OCPP integration, you have the option to change the name of all associated entities from the default. Originally I chose Wallbox so all my entities were prefixed accordingly. More entities were added later but these appeared with a prefix of charger instead of Wallbox.

I couldn't find any way to go back and rename the new ones with a prefix of Wallbox so I ended up removing the OCPP integration and adding it back again, this time leaving the name set to the default of charger so I don't have the same problem in future.

If there is any easy way to rename entities which are added later, I should document this in the Wiki, otherwise I should warn users about the difficulty they will experience if they change the device name from the default.

@lbbrhzn @drc38 - Let me have your comments please

[drc38]

There's no easy way to update sensor names that I'm aware of. As long as you use a consistent name for the charger every time you reinstall you're ok. The integration can support multiple chargers by giving them unique names.

[GrantKeymer]

My point is that if you want to avoid re-installing, rather just taking the integration updates via HACS as they become available, then you don't have any control over the prefix used for newly added entities. They all end up with a prefix of charger.

Therefore, it's probably best to leave the device name charger in place so all entities have the same prefix. Does that make sense?

[drc38]

My point is that if you want to avoid re-installing, rather just taking the integration updates via HACS as they become available, then you don't have any control over the prefix used for newly added entities. They all end up with a prefix of charger.

Therefore, it's probably best to leave the domain name charger in place so all entities have the same prefix. Does that make sense?

They shouldn't, I've never had that issue and always used a non-default charger name.

If it can happen though worth mentioning.

[GrantKeymer]

Hmmm, that's interesting. It definitely happened to me with the recently added _status_connector and _error_connector entities.

[lbbrhzn]

Please note there are two places where a name/identity for a charger can be entered. The charger name in the configuration panel and the charger identity (entered when configuring the url). We currently use the config name for creating the entities, but use the charger identity for the connection. There is code in place for supporting multiple chargers, but that has not been tested and I don't think it works.

[drc38]

I thought @McFranky had more than 1 connected?

[GrantKeymer]

Please note there are two places where a name/identity for a charger can be entered. The charger name in the configuration panel and the charger identity (entered when configuring the url). We currently use the config name for creating the entities, but use the charger identity for the connection.

Excellent, thanks for clarifying that.

[McFranky]

@drc38 I have 7 instances of Server/Client installed.

[GrantKeymer]

@lbbrhzn - When you're ready, please create a blank Wiki page in .MD format with your OCPP logo at the top. I'll fork and start work from there. Thanks!

[GrantKeymer]

@lbbrhzn - Thanks for creating the blank Wiki page with logo for me. Now I have my first page ready to be merged with your repo but I can't seem to make a Pull Request to action this. It keeps saying that...

There isn’t anything to compare.
lbbrhzn:main is up to date with all commits from GrantKeymer:main

Probably me not understanding how PRs work, but I just wonder, do they only work with code and not documentation?

Here is my Wiki page... https://github.com/GrantKeymer/ocpp/wiki

[lbbrhzn]

Many thanks for the updated documentation, great job!
Unfortunately, looks like PRs only only work for the main repo, not for the wiki. There are some workarounds in use, see:
https://stackoverflow.com/questions/10642928/how-to-pull-request-a-wiki-page-on-github
Not sure what would be the best approach in our case.

[drc38]

As long as I don't update the firmware or need to change my HA ip address then I'll be ok continuing to use the Evnex. I think the lock-in approach will hurt them in the long run as chargers are just one part of the future demand response eco-system.

[lbbrhzn]

@GrantKeymer the automatic push to wiki is now working as well.

The whole procedure for updating the documentation works similar to updating the source code:

• fork the repo (if not done already)
• clone the fork (if you want to work locally)
• create a new branch for storing your changes
• change the .md files in the /docs folder on the branch (either locally or through the GitHub web interface)
• add, commit and push your changes (local)
• create a pull request

The pull request can then be reviewed, and merged to master after approval. The merge will trigger an update to readthedocs and to the wiki of lbbrhzn/ocpp.
When a new release is made, the documentation corresponding to that release will be added to readthedocs.
The wiki will always reflect the latest changes.
Note that updating the wiki directly (instead of using /docs) will not work. The /docs folder is leading and will overwrite whatever is in the wiki.

[GrantKeymer]

@GrantKeymer the automatic push to wiki is now working as well.

The whole procedure for updating the documentation works similar to updating the source code:
...
Note that updating the wiki directly (instead of using /docs) will not work. The /docs folder is leading and will overwrite whatever is in the wiki.

Excellent! Thanks for the very detailed explanation. I'll give it a try in the next few days.

[GrantKeymer]

My favorite is of course number.evbox_maximum_current. It made me sit down and create some fuse protection.

Haha, I love the overcurrent warning using Alexa and Telegram 🤣

Thanks for all the other explanations. That will make for a very detailed Wiki page 👍

[GrantKeymer]

@GrantKeymer the automatic push to wiki is now working as well.

The whole procedure for updating the documentation works similar to updating the source code:

• fork the repo (if not done already)
• clone the fork (if you want to work locally)
• create a new branch for storing your changes
• change the .md files in the /docs folder on the branch (either locally or through the GitHub web interface)
• add, commit and push your changes (local)
• create a pull request

The pull request can then be reviewed, and merged to master after approval. The merge will trigger an update to readthedocs and to the wiki of lbbrhzn/ocpp. When a new release is made, the documentation corresponding to that release will be added to readthedocs. The wiki will always reflect the latest changes. Note that updating the wiki directly (instead of using /docs) will not work. The /docs folder is leading and will overwrite whatever is in the wiki.

@lbbrhzn - I'm finally coming back to this after getting other stuff out of the way. I've deleted the old repo fork I made some time ago because it was well out of date, then created a fresh fork. I don't need to work locally so I didn't clone the fork. However, I can't see how to Create a new branch even after looking at the GitHub Docs. This is the nearest option I can find...

I suspect it's the wrong option to use, but can't see any way to Create a new branch as instructed. Thanks 🤦‍♂️

[lbbrhzn]

hi @GrantKeymer , please note that you should not fork the wiki, but the code repository.
You can then create a new branch by clicking on 'main'. Then enter your branch name, and select 'create branch'.