v2 API suggestions

[alex-Arc]

I am working on a port to arduino https://github.com/alex-Arc/companion-satellite-arduino

And have come across a couple of things I think should be changed

BEGIN message

Upon connection you will receive BEGIN Companion Version=2.2.0-d9008309-3449 stating the build of companion you are connected to. This should not be relied on to be meaningful to your application, but can be presented as information to the user, or to aid debugging.

• Should I not rely on this to chenk that the V2 API is suported. Or could we send a different message with the API version?
• should it not be "Companion_Version" or is "Companion" just at loose Arg without meaning?

VAL with spaces

Messages follow the general format of COMMAND-NAME ARG1=VAL1 ARG2 ARG3="VAL3 with spaces"\n.

could we not prohibit spaces in values or or auto translate them to and from _ this would make parsing much more simple.

ARG without a value is the same as TRUE"

Messages follow the general format of COMMAND-NAME ARG1=VAL1 ARG2 ARG3="VAL3 with spaces"\n. Note the ARG2 which is shorthand for ARG2=true

is it really worth it to save to save the data and nort write the true every time, for the added complexety in parasing the message? (we could also change it to 1 and 0 if we want to save data)

If kept every ting should at least default to false so that you only get what you ask for. see -> https://github.com/bitfocus/companion/wiki/Satellite-API#adding-a-satellite-device -> Optional parameters: -> BITMAPS

Module Status (enhancement)

get the relevant module status, like the small square at the top of the streamdeck button maybe KEY-STATE STATUS=OK KEY-STATE STATUS=WARN and KEY-STATE STATUS=ERROR

Companion log (enhancement)

The connection and disconnection of a Satellite should be logged in companion

vh Alex :-)

[Julusian]

Thanks, some good feedback here.

BEGIN message

• Should I not rely on this to chenk that the V2 API is suported. Or could we send a different message with the API version?

Yeah, an api version should be included here. I haven't felt it needed, but new features have been added and clients will need to know what functionality is available..

• should it not be "Companion_Version" or is "Companion" just at loose Arg without meaning?

Yeah, that should probably be changed to Companion_Version

VAL with spaces

Maybe. I'm not keen on using _ instead of spaces, as that makes things lossy, but perhaps places where spaces are allowed could be limited and those fields could require them to be base64 encoded instead. I think this needs some thought on whether that is better or not.

ARG without a value is the same as TRUE

This is only true for messages sent to compnaion, never is reponses so you can ignore that note. Ill drop that from the docs to make that clear (its not much benefit to use shorthand anyway)

Module Status (enhancement) & Companion log (enhancement)

Good ideas

[Julusian]

In the latest build, BEGIN has changed following this discussion https://github.com/bitfocus/companion/wiki/Satellite-API#api-spec