Announcement

Collapse
No announcement yet.

HS-392 - Feature - Enhance ASCII Interface

Collapse
X
 
  • Filter
  • Time
  • Show
Clear All
new posts

    HS-392 - Feature - Enhance ASCII Interface


    New Feature Proposal:
    I'd like to see an enhanced ASCII / Telnet interface using a JSON format for the data.
    This could be carried on a separate port number from the current JSON data so that it could be distinguished from the current ASCII port.

    Currently, when a command is sent over the Telnet interface, you typically get back an "OK" or an error, but it isn't always clear which command that "OK" responds to. This creates a tracking problem if the program that is interfacing with HomeSeer operates asynchronously (e.g., a Javascript program). So, as a starting point, it would be beneficial if the telnet interface passed a hash token back and forth so that commands / responses can be tracked. That is, each time a command is sent to HomeSeer, the program sending the command will specify a "hash" value (which can be any program-selected value as long as all outstanding hash values are unique). When HomeSeer responds to the command, it will include that hash value in its response.

    For example, sending a command would involve send a JSON structure along the following lines:
    {
    "command": "command"
    "reference": reference:
    "value": XXX
    "hash": "XXX"
    }

    There may also be a similar structure using a value_label instead of a numeric value.


    In response, you would get back a report:
    {
    "report type": "command_result",
    "result": " string",
    "value_sent", original_sent_value
    "result value": new_device_value
    "hash": "XXX"
    }

    Where "result" would be the response message - e.g., "OK" or an error message.
    I suggest reporting both the "original_sent_value" and "new_device_value" as this is useful where, for example, you send a "255" to a dimmer (last value) resulting in a report that the new dimmer has responded but it was set to "55" as the new value.

    For commands that take a long time to process (for example, a "last value" sent to a dimmer), you could consider a two-stage report.
    a) a "command pending" report including the original hash which indicates that the command was received but processing is not complete, and then
    b) a "command_result" report when the command finishes-- the result report would then include the new value.



    Autonymous reports (i.e., those sent when the value of a HomeSeer device changes from the HomeSeer) could be something like:
    {
    "report_type": "Device Report",
    "reference": XXX
    "time": (epoch time when new value was set)
    "new_value": value,
    "old_value": old_value,
    "last_changed": (epoch time when was the "old_value" was set),"
    "status_use":
    "control_use":
    }

    Where the "control_use" identifies the "Control Use" for the value, if any, that is specified on the HomeSeer "Status Graphics" page for the device, and the "status_use" corresponds to a value in line with the proposal here: https://forums.homeseer.com/forum/de...to-control-use


    Update: 1/19/2020: As a clarification, it should be possible for multiple values to be assigned the same "status use", and if a device has a "control use", then when the report is generated, both the "control use" and its "status use" values get reported, though if a device is "status only" then only the "status use" gets reported.

    #2
    would be nice to be able to change a value of a '' status devices'' ( so without control) with the telnet /acii interface

    Code:
    http://127.0.0.1:XX/JSON?request=setdevicestatus&ref=2924&value=42
    This means i set device #2924 to the value of 42.


    So a similar call for telnet would be nice :

    Code:
    SV,2924,42
    rjh macromark

    Comment


      #3
      rjh Why not replace the telnet interface for an ssh one with the same fonctionnalities + the ones we asked above?

      Comment


        #4
        Ssh is more secure

        Comment


          #5
          Originally posted by MattL0 View Post
          rjh Why not replace the telnet interface for an ssh one with the same fonctionnalities + the ones we asked above?
          From a development/integration perspective SSH is a PITA to use. There's also issues with new client connections and accepting the certs or creating the certs for password-less connections. I would not like to see this. Telnet is perfectly fine for a internal ASCII based interface that is not intended to be used remotely. For a remote and secure interface a websocket interface would be preferred.

          I think to satisfy jvm I think a websocket interface with JSON output would be very nice to have. This could even be a bi-directional websocket that clients could subscribe to for status and control of HS devices.

          Comment


            #6
            Originally posted by jvm View Post
            Currently, when a command is sent over the Telnet interface, you typically get back an "OK" or an error, but it isn't always clear which command that "OK" responds to. This creates a tracking problem if the program that is interfacing with HomeSeer operates asynchronously (e.g., a Javascript program).
            Not sure if I can follow here. When doing a request, you're getting the reply right away, or is my assumption incorrect (haven't used the ascii interface) ? If that is the case, what would be the added value of the hash in the reply ?

            Comment


              #7
              Originally posted by kriz83 View Post

              Not sure if I can follow here. When doing a request, you're getting the reply right away, or is my assumption incorrect (haven't used the ascii interface) ? If that is the case, what would be the added value of the hash in the reply ?
              The reply on the ASCII interface is immediate and it is serial. Send/Recv. I think what is happening here is trying to apply a JS async methodology to a serial sync process.

              Comment


                #8
                That was my idea too, but in that case you don't need a hash ?

                Comment


                  #9
                  Originally posted by kriz83 View Post
                  That was my idea too, but in that case you don't need a hash ?
                  A hash isn't needed as long as you're programming in the correct method of dealing with a serial/sync interface.

                  Comment


                    #10
                    Originally posted by simplextech View Post

                    The reply on the ASCII interface is immediate and it is serial. Send/Recv. I think what is happening here is trying to apply a JS async methodology to a serial sync process.

                    I assumed that not all responses are immediate so the hash could be helpful. For example, if a plugin took a long time to process a command, my assumption is that the response could be delayed and that serial order between different commands / responses wasn't guaranteed. Also, the plugin code for my homebridge plugin is in Javascript which is inherently async, so it would be useful to have a hash to help correlate commands and responses. Basically, having the hash as an optional field is negligible overhead but can be helpful to the programmer, so it doesn't hurt to include it.

                    Comment


                      #11
                      Originally posted by simplextech View Post

                      From a development/integration perspective SSH is a PITA to use. There's also issues with new client connections and accepting the certs or creating the certs for password-less connections. I would not like to see this. Telnet is perfectly fine for a internal ASCII based interface that is not intended to be used remotely. For a remote and secure interface a websocket interface would be preferred.

                      I think to satisfy jvm I think a websocket interface with JSON output would be very nice to have. This could even be a bi-directional websocket that clients could subscribe to for status and control of HS devices.
                      I think that's right. Basically, I needed a non-polling interface for status and control so that I could get updates rapidly - that's why the HTTP based JSON interface as currently implemented does't work. If there was a WebSocket API that had an always-connected connection so I didn't have to poll for changes, that would work fine - I suppose it might be better than what I proposed.

                      Comment


                        #12
                        Originally posted by jvm View Post

                        I think that's right. Basically, I needed a non-polling interface for status and control so that I could get updates rapidly - that's why the HTTP based JSON interface as currently implemented does't work. If there was a WebSocket API that had an always-connected connection so I didn't have to poll for changes, that would work fine - I suppose it might be better than what I proposed.
                        Yeah the current JSON interface wasn't developed for interactive or real-time use I don't think. I've never really understood that design. The older ASCII interface was developed for interactive real-time use for HSTouch and others have adopted it for user integrations as well.

                        Going back to your hash or method to recognize the device... if I remember correctly (it's been a while) each send and receive from the session includes the Device ID so you could use that as the hash maybe. The only thing lacking here is a timestamp (I think).

                        Comment


                          #13
                          Originally posted by simplextech View Post

                          Yeah the current JSON interface wasn't developed for interactive or real-time use I don't think. I've never really understood that design. The older ASCII interface was developed for interactive real-time use for HSTouch and others have adopted it for user integrations as well.

                          Going back to your hash or method to recognize the device... if I remember correctly (it's been a while) each send and receive from the session includes the Device ID so you could use that as the hash maybe. The only thing lacking here is a timestamp (I think).
                          I would like to be able to know if I'm receiving a device update in response to a command sent to the plugin, or if it was generated on the device / HomeSeer side, so the hash would be useful. As I see it, if HomeSeer does any update to the JSON or telnet interfaces, adding code to repeat back a hash is trivial, so it's in the "of course this should be added - its so trivial to implement" category. At this point, my HomeKit plugin is working fine without these additions, though it would have been much easier to implement / test / diagnose it when I was developing it if I could have sent the hash value and known when a received update was in response to something I sent to HomeSeer - so this suggestion is more in the nature of something that would help in the future, but isn't critical to me right now category.

                          Comment


                            #14
                            Originally posted by jvm View Post

                            I would like to be able to know if I'm receiving a device update in response to a command sent to the plugin, or if it was generated on the device / HomeSeer side, so the hash would be useful. As I see it, if HomeSeer does any update to the JSON or telnet interfaces, adding code to repeat back a hash is trivial, so it's in the "of course this should be added - its so trivial to implement" category. At this point, my HomeKit plugin is working fine without these additions, though it would have been much easier to implement / test / diagnose it when I was developing it if I could have sent the hash value and known when a received update was in response to something I sent to HomeSeer - so this suggestion is more in the nature of something that would help in the future, but isn't critical to me right now category.
                            Only problem with adding to old stuff is breaking of existing integrations. This is very true of the ASCII interface where it has a set/defined input/return and changing that would break lots of things. With that though I'm all in favor of a websocket interface that would bring this type of functionality.

                            Comment


                              #15
                              Originally posted by simplextech View Post

                              Only problem with adding to old stuff is breaking of existing integrations. This is very true of the ASCII interface where it has a set/defined input/return and changing that would break lots of things. With that though I'm all in favor of a websocket interface that would bring this type of functionality.
                              Agreed with the concern about breaking older apps that use the existing format. This is why I suggested that the updated ASCII interface be provided via a different port number and be JSON based so it can be more easily enhanced without breaking things in the future.

                              Comment

                              Working...
                              X