Hotel Apartment Json Server

<< Click to Display Table of Contents >>

Navigation:  Schnittstellen >

Hotel Apartment Json Server

Link

 

Diese Schnittstelle ist für Hotel Apartments.

 

Drittanbieter können über diese Schnittstelle alle Datenpunkte steuern.

 

Die Datenpunkte werden den Apartments/Räume zugeordnet.

 

Diese können extern über einen TCP Socket ausgelesen und gesteuert werden.

 

Die Kommunikation erfolgt im Json Format.

 

 

 

Im Server unter "Einstellungen" - "Schnittstellen" wird die Schnittstelle konfiguriert.

 

Apartment Server

 

 

Die Schnittstelle darf nur einmal angelegt werden.  In der Schnittstellen Konfiguration wird der Port des TCP Socket angegeben.

Die Drittanbieter Software muss sich auf diesen Port und auf die IP Adresse des Server verbinden.

 

 

 

Apartments anlegen:

 

Die Apartments und deren Räume werden unter "Einstellungen" - "Hotel Apartments" eingerichtet.

 

Apartment Konfig

 

 

Es können beliebig viele Apartments und Räume eingerichtet werden.

Die Räume werden im jeweiligen Apartment angelegt.

 

Die Datenpunkte werden den Räumen zugeordnet. Diese müssen zuvor unter "Einstellungen" - "Datenpunkte" angelegt werden, anschließend können diese zugeordnet werden.

 

 

TCP Kommunikation:

 

Die Kommunikation erfolgt über einen TCP Socket.

 

Jedes Telegramm wird mit einem CR am Ende versendet. (Windows "\r\n" , Mac und Linux "\n" ).

 

Der Port muss in der Server Firewall freigegeben sein.

 

 

 

Alle Apartments auslesen:

 

Über folgenden Befehl werden alle Apartments aufgelistet.  Die ID wird automatisch vom Server generiert und kann nicht geändert werden.

Der Name kann jederzeit geändert werden.

 

Json Befehl:

 

       {  "command":  {  "name": "get_apartments" } }

 

Json Antwort:

 

 { "apartments": [   {"name":"Wohnung 1","id":1} ,  {"name":"Wohnung 2","id":2} ,  {"name":"Wohnung 3","id":3}  ]  }

 

 

 

Einzelnes Apartment auslesen:

 

Über die Apartment ID kann ein einzelnes Apartment abgefragt werden.

 

Jedes Apartment muss separat abgefragt werden. Es kann immer nur ein Apartment abgefragt werden.

 

In der Antwort des Server wird das Apartment mit Name und ID sowie alle Räume und Datenpunkte aufgelistet. Jeder Datenpunkt enthält die Apartment ID und Raum ID, hierüber werden die Datenpunkte den Räumen zugeordnet.

 

Jeder Datenpunkt enthält Status und Befehl Informationen.

 

Über den description und type Wert können Befehle und Status unterschieden werden.

 

 

Json Befehl:

 

  {  "command":  {  "name": "get_apartment_config" , "id": "1" } }

 

Json Antwort:

 

{

 "apartment_config":

 {

  "apartment":

         {

                 "name":"Wohnung 1",

                 "id":1

         },

 

 "rooms":

 [

         {

                 "name":"Wohnzimmer",

                 "id":1

         },

 

         {

                 "name":"Bad",

                 "id":2

         },

 

         {

                 "name":"Küche"

                 ,"id":3

         }

 ],

 

 "datapoints":

 [

         {

                 "apartment_id":1,

                 "room_id":1,

                 "datapoint_name":"Licht Wohnzimmer",

                 "datapoint_type":"light",

                 "datapoint_id":10,

 

                  "commands":

                 [

                         {

                                 "command_id":"20",

                                 "gateway_id":"1",                                        

                                 "command_type":"Bool_On_Off",

                                 "command_name":"Licht Wohnzimmer",

                                 "description":"command_bool"

                         },

 

                         {

                                 "command_id":"21",

                                 "gateway_id":"1",        

                                 "command_type":"Bool_On_Off",

                                 "command_name":"Licht Wohnzimmer",

                                 "description":"command_bool"

                         }

                 ]

                 ,"states":

                 [        

                         {

                                 "state_id":"24",

                                 "gateway_id":"1",

                                 "state_unit":"",

                                 "state_name":"Licht Wohnzimmer",

                                 "state_type":"Bool_On_Off",

                                 "state_value":"true",

                                 "description":"state_bool"

                         }

                 ]

         },

 

         {

                 "apartment_id":1,

                 "room_id":2,

                 "datapoint_name":"Licht Bad",

                 "datapoint_type":"light",

                 "datapoint_id":11,

 

                 "commands":

                 [

                         {

                                 "command_id":"20",

                                 "gateway_id":"1",                

                                 "command_type":"Bool_On_Off",

                                 "command_name":"Licht Bad",

                                 "description":"command_toggle"

                         },

 

                         {

                                 "command_id":"20",

                                 "gateway_id":"1",                

                                 "command_type":"Bool_On_Off",

                                 "command_name":"Licht Bad",

                                 "description":"command_bool"

                         }

                 ]

 

                 ,"states":

                 [

                         {

                                 "state_id":"24",

                                 "gateway_id":"1",

                                 "state_unit":"",

                                 "state_name":"Licht Bad",

                                 "state_type":"Bool_On_Off",

                                 "state_value":"true",

                                 "description":"state_bool"

                         }

                 ]

         }

 ]

    }

 

}

 

 

Kommando Typen ( command_type )

 

Es gibt verschiedene Kommando und Status Typen.

Über diese können dies unterschieden und in der Drittanbieter Software entsprechend dargestellt werden.

 

Bool_On_Off        - Parameter: "true" oder "false"

Bool_On                - Parameter: keine

Bool_Off                - Parameter: keine

Bool_Set_Number        - Parameter: keine

Bool_Set_Text        - Parameter: keine

Bool_Pulse                - Parameter: keine

Datetime                - Parameter: Long Zeit

Decimal                - Parameter: Nummerischer Wert

Percent                - Parameter: Nummerischer Wert 0-100

String                        - Parameter: Text Wert

 

 

 

Status Typen ( state_type )

 

 

Bit                        -Wert: "true" oder "false"

Bool_On_Off                -Wert: "true" oder "false"

Datetime                -Wert: Long Dezimal

Decimal                -Wert: Dezimal

Image                        -Wert: Base64

Percent                -Wert: Dezimal 0-100

String                        -Wert: Text

Decimal_Bool        -Wert: "true" oder "false"

 

 

 

 

  Befehle senden:

 

  Die Datenpunkte werden über Befehle gesteuert.  Diese werden in der Apartment Konfiguration bei dem jeweiligen Datenpunkt aufgelistet.

 

  Für einen Befehl ist die command_id und die gateway_id notwendig. Über diese 2 Parameter wird der Befehl vom Server erkannt.

  Eine Datenpunkt ID ist nicht notwendig. Über den command_parameter wird der Wert übertragen. Dieser ist nicht immer erforderlich.

 

  Die command_id ist nicht unique.  Diese fängt bei jedem Gateway mit der ID 1 an.

 

  Datenpunkte steuern:

 

  {  "command":  {  "name": "send_command" , "command_id": "209",  "gateway_id": "1" } }

  {  "command":  {  "name": "send_command" , "command_id": "210",  "gateway_id": "1", "command_parameter": "true" } }

  {  "command":  {  "name": "send_command" , "command_id": "210",  "gateway_id": "1", "command_parameter": "false" } }

  {  "command":  {  "name": "send_command" , "command_id": "211",  "gateway_id": "1", "command_parameter": "60.0" } }

 

 

 

 Datenpunkt Updates für Apartment anfordern:

 

 Jedes Apartment muss im Server für Status Updates registriert werden. Nur dann werden Status Updates der zugeordneten Datenpunkte übertragen.

 Mit dem id Parameter wird die ID des Apartment angegeben.

 

 

  {  "command":  {  "name": "get_apartment_state_updates" , "id": "2" } }

 

 

 

 

  Status Update bei Änderung eines Datenpunkt Status:

 

  Das Status Update enthält immer die state_id und gateway_id. Über diese 2 Parameter kann der Status eindeutig identifiziert werden.

 

  Die state_id ist nicht unique.  Diese fängt bei jedem Gateway mit der ID 1 an.

 

 

  { "datapoint_update":  { "state_name": "state_bool"  , "state_id": "22" , "gateway_id": "1" , "state_value":"true" }  }

 

 

 

  Kommunikation und Updates beenden:

 

  {  "command":  {  "name": "exit"  } }

         

 

         

  Server Antwort:

         

  {  "command_response":  {  "state": "error" , "value": "description of error"  } }

    {  "command_response":  {  "state": "successful" , "value": "successful"   } }