Update documentation

[scottbonline]

No description provided.

[futzlarson]

This would be great. I see "There are plenty of methods for you to call" but is there a list somewhere?

[kbickar]

Pretty much all the functions in this file: https://github.com/scottbonline/sense/blob/stable/sense_energy/senseable.py

[futzlarson]

Cool, I'll submit a PR to update the docs.

[futzlarson]

I haven't done that before for an open-source project. Should it be off master or a new branch?

[Blackcell]

I haven't done that before for an open-source project. Should it be off master or a new branch?

If it is a PR I think branching off master should work.

[futzlarson]

Can someone familiar with the code provide one-sentence descriptions for these methods? I have not used it, just trying to help the documentation so that more people can. I have descriptions for the rest from the source.

get_trend_data
get_discovered_device_names
get_discovered_device_data
get_all_usage_data

[kbickar]

First it's important to know there are two implementations, the async version and the sync version. Apps that use async IO can use the async version, pretty much everyone else will want the sync version.

Then there are two types of API calls made by the library. Those to get the realtime data, and those to get trend/device/usage/historic data.

As for the functions:

get_trend_data fetches the trend data for a scale of time (e.g. day, month, year). It's mostly used when called by update_trend_data which will get the trend data for all of the scales

get_discovered_device_names returns a list of the names of devices discovered

get_discovered_device_data returns a list of the discovered devices including all the data available on the API (name, type, powered on, etc)

get_all_usage_data had a bug and didn't work, I just pushed a fix. It returns the last 30 usage events like devices being turned on for X minutes

I also just removed the function get_notification_preferences as it no longer worked

[futzlarson]

Thanks! I'm about to push a PR that has documentation on methods. While I know what sync and async mean, I don't know exactly what it means in this context. Feel free to add that info as it also seems like useful info.

[israndy]

I was curious about this API as well. I got it working very quickly, thank you, grabbing my solar vs my usage to figure out if I had any free solar and I wrote an app (TesSense) that allows my Tesla to change the rate it charges at.

Then I wanted to know more about the API and I just finished the app SenseAPI.py (https://github.com/israndy/SenseAPI) that lets you call each of the functions. But a few of them are not obvious and could use some documentation. The Example Async code must have some dependancies that I don't understand

[kbickar]

The async code (for the Kasa emulation) should only require asyncio to be imported. Aside from that the async and non-async versions behave pretty similarly. Which functions need documenting more?

Side note: might not want to include login credentials in something you put publicly online

[israndy]

Dammit! not again. Oh, I see. Xcode makes every little change I make in the editor to the file on the drive. I thought if I saved the file I could upload the version w/o my password in it but I was pasting the password back in w/o saving it before I uploaded. Why even have a save function? Especially if it then prompts me that I have unsaved changes if I try to close the file. Well, lesson learned (I hope).

…

On Mar 11, 2022, at 1:40 PM, Keilin Bickar ***@***.***> wrote: Side note: might not want to include login credentials in something you put publicly online

[israndy]

When I try to paste your example into my SenseAPI.py script and then put 'import asyncio’ before it, I get the error: ModuleNotFoundError: No module named 'sense_link' I am probably suffering from already having tried to run the other SenseLink on this same computer so there are some dependancies that I need to squash, or I don’t know how to link code so well. Any thoughts? I also notice when I run print( "Senseable:\n", dir( Senseable ) ) # shows all the Sense API functions That I get a couple of calls I am not familiar with: ‘Devices' jumps out at me, I also haven’t figured out how to retrieve ‘get_realtime_stream' data. Both ‘get_trend' and ‘trend_start' are probably related. There’s also ‘load_auth' and ‘set_auth', and ‘set_realtime' I don’t know how to use ‘api_call', but I assume all the current API calls are available in your code and this is just in case a programmer wants to call one directly. And ‘set_ssl_context' is probably similar, but I don’t know. I wrote SenseAPI.py as a way to document making calls to your API so if you can send a hint at what these calls require I’ll add them to my code for others to learn from.

…

On Mar 11, 2022, at 1:40 PM, Keilin Bickar ***@***.***> wrote: The async code (for the Kasa emulation) should only require asyncio to be imported. Aside from that the async and non-async versions behave pretty similarly. Which functions need documenting more?

[kbickar]

I added a little more documentation for a few of the key functions. In terms of structure, there are two main parts the library:

• The Sense Web API interface
• The Local smart plug interface

For the web API (Senseable or AsyncSenseable objects) there is long term "Trend" data and instantaneous "Realtime" data. The realtime data can be read either as just one update (what the current devices are doing now), or as a stream of updates (similar to viewing in the app).

For the smart plug interface (SenseLink object), its purpose is to run a server that replies with available smart plugs and sends out updates when requested by the monitor. It won't really do much by itself