sc14dectipbs web api v1.3

Upload: kostas-zafeiropoulos

Post on 01-Jun-2018

217 views

Category:

Documents


0 download

TRANSCRIPT

  • 8/9/2019 Sc14dectipbs Web API v1.3

    1/13

    SC14DECTIPBSWeb Application Interface (API)

  • 8/9/2019 Sc14dectipbs Web API v1.3

    2/13

    April 10, 2012 v1.1 Dialog Semiconductor B.V. page 2 of 13

    SC14DECTIPBS

    WebAPI

    Revision history:Version Released Responsible CommentsV1.0 13-Dec-11 KZ Initial releaseV1.1 10-Apr-12 KZ Updated commands to reflect latest API

    1.0 API DESCRIPTION

    1.1 General command formatThis document describes the interface which is used to access ULE functionality from any IP based network. For thecommand structure a JSON (Javascript Serial Object Notation) format is used, which is a fat-free alternative to XML.The format is used due to the extensive number of libraries available for different languages (PHP, C++, C#,Javascript, Qt, Java, ASP). Please visit www.json.org for more information.

    1.2 Using the web based APIThe JSON command string will be passed over standard HTTP traffic. The general idea of the DECT IP BSterminated API is the following:

    The DECT IP BS uses DHCP to obtain an IP address within the network (LED 1 will light up upon successfuladdress discovery).

    The DECT IP BS can then be reached by its hostname DECTIPBS (number is printed/written onthe PCB itself). If the DHCP router does not resolve DNS name, the board can be directly accessed by its IPaddress. The address can be obtained by running the DECT-ULE-SetupWizard in VM /home/uleuser/ folder.

    The API can be accessed through a HTTP GET call in the following wayo http://DECTIPBS/getJson.json?jsonString =”....” for sending/receiving single command

    strings.o http://DECTIPBS/testJson.json for test page to test the response for given JsonStringo This call can be done in a number of ways:

    Using a standard browser (or cURL) allows the user to test single commands and read theoutput in the browser window

    Some type of webapplication using AJAX calls or HTTP forms An extensive example using this interface is the demo webpage code found in the source code

    /RHEA_ULE_Release_/SW/source/user/sc1445x_dect_apps/ULE/apps.

    Please note that: The IP BS will be reachable through hostname in the internal network, but NAT translations will need to be

    done to reach the device outside of the network gateway. Alternatively the board can connect to outsidenetwork to a server from which user can access any registered board. The board is connected automaticallyduring boot up and no port forwarding is needed in this case. For more details refer to SW manual at SW

    Architecture portal server section.

    1.3 Testing the commandsUse the following steps to go to an API test page running on the DECT IP BS:

    Run the DECT-ULE-SetupWizard. Locate the board and note down the IP. As an example the IP could be 192.168.0.101

    Open a browser and go to http://192.168.0.101/testJson.json In the command entry box JSON commands can be entered

    The commands examples can be executed as examples in the Command entry box.

    Alternatively the SmartPulse portal server can be used to test various commands on the board. Please see the QuickStart Guide in order to see how JSON commands can be tested through the portal server.

    http://www.json.org/http://192.168.0.101/testJson.jsonhttp://192.168.0.101/testJson.jsonhttp://www.json.org/

  • 8/9/2019 Sc14dectipbs Web API v1.3

    3/13

    April 10, 2012 v1.1 Dialog Semiconductor B.V. page 3 of 13

    SC14DECTIPBS

    WebAPI

    1.4 General ULE command format

    The following string is a typical example of a JSON string used for the DECT IP BS:

    [{"cmdType":0,"portId": 1,"packId": 12,"data":[0,1,2]}, {"cmdType":1,"portId":{},"param":[{"paramId":8,"paramValue":1}]

    The string is an array (indicated by []) of commands (indicated by comma separated {}). All high level commands

    contain the following common elements:

    Parameter Description Values CommentscmdType Identifies command type 0 – Data command

    1 – Configuration command2 – System command3 – User command

    portId Identifies the port to whichthe command is sent to orreceived from

    7 – 64 PortID 1-6 is reservedfor no ULE devices.

  • 8/9/2019 Sc14dectipbs Web API v1.3

    4/13

    April 10, 2012 v1.1 Dialog Semiconductor B.V. page 4 of 13

    SC14DECTIPBS

    WebAPI

    1.5 Detailed ULE command formats

    1. Data command: (“cmdType”: “0”)

    Data commands are used for holding send and receive data for sensors.They are issued in the following format:Packet holding send data:

    { “cmdType":"0","portId": "","EarlyBit":"< EarlyBit >",“data”:”” }

    Example:[{"cmdType":0,"portId":1,"data":[49,69,0,1,1,0,0,0,0,0,0,0,0,0,0,0,0,0,0]}]

    Example with paging and earlybit set:[{"cmdType":0,"portId":1," EarlyBit": 1,"data":[49,69,0,1,1,0,0,0,0,0,0,0,0,0,0,0,0,0,0]}]

    Packet holding received data:{ “cmdType":"0","portId": ""," packId":"< packId>"," TimeStmp":"< TimeStmp>", " SensorType":"<SensorType>", " DataType":"< DataType>", " NextMess":"< NextMess >", “data”:”” }

    Example:[{"cmdType":0,"portId":1, >"," packId":12," TimeStmp":2345, " SensorType":49, " DataType":29,"NextMess":0, "data":[14,15,16,1,1,0,0,0,0,0,0]}]

    Fields are numbers and data field is an array of decimal data values.This command is used to send data to sensors.Note: Refer to Appendix B for payload format.

    Returns JSON string status:

    {"cmdType":0,"portId":,errDesc": UleErrEnum }

    UleErrEnum : ULE_Success for success or else refer to APPENDIX A for error typeImportant: ULE_Success does not mean that the packet was transmitted successfully. Refer to Appendix C.

    Parameter Description Values

    PortId Identifies the portable part from whichthe message is send from/to.

    00-64

    PackId Identifies packet number. Used onlywhen receiving a packet. It is 32 bitnumber unique for each sensorreceived packet.

    00 – 0xFFFFFFFF

    Timestamp Identifies the time in seconds whichthe packet got received

    00 – 0xFFFFFFFF

    SensorType Identifies the type of sensor whichsend the packet for example (button,actuator, relay, etc)

    SENSOR_TYPE_GENERIC = 0x01 ACTUATOR_TYPE_GENERIC = 0x02

    DataType Identifies the type of message(wakeup, alarm, HAL, batterylow,etc)

    MMI_DATA_TYPE_KEEP_AWAKE=0x01MMI_DATA_TYPE_HAL= 0x13MMI_DATA_TYPE_WAKEUP_CFG=0x14

    NextMessage Identifies whether all the information is

    contained in one message or not.0 – One message1 – Data continue in next message

    EarlyBit Identifies whether paging and Early Bitfeature will be used or not. Used onlywhen sending a packet.

    0 – Paging enabled and send EarlyBit =01 – Paging enabled and send EarlyBit =12 – Paging disabled (default value ifomitted)

    Data Data payload send to the portabledevice

    1 to 56 decimal numbers

  • 8/9/2019 Sc14dectipbs Web API v1.3

    5/13

    April 10, 2012 v1.1 Dialog Semiconductor B.V. page 5 of 13

    SC14DECTIPBS

    WebAPI

    2. ULE c onfiguration command (“cmdType”: “1”):

    Parameters commands are issued in the following format:

    {"cmdType":1,"portId":","param":[{"paramId":,"paramValue": }, … }]}

    Or for a single paramID:

    {"cmdType":1,"portId":", “paramId":,"paramValue":}

    Example:

    {"cmdType":1,"portId": 1,"paramId":8,"paramValue":1}

    Fields are numbers and Param field is an array of JSON paramId/Paramvalue structure.

    For write command this command returns:

    {"cmdType":1,"portId":,errDesc": UleErrEnum }UleErrEnum : ULE_Success for success or else refer to APPENDIX A for error type

    For read/request command this command returns:

    {"cmdType":1,"portId":, errDesc":0, "paramId":, paramValue:} for SUCCESS

    {"cmdType":1,"portId":,"paramId":, errDesc": UleErrEnum } for FAIL. Refer to APPENDIX A forerror type

    When issuing a read request with portiD:{}, the response is gernerated for all available portID.Valid range for portID is from 7 to 64.When issuing a read request for a parameter an empty array is used, so the format shall be:“”:{}

    ParamID

    Values

    Description Read

    /Write

    Comments

    1 – 8 Port parameters - See values below for details

    1 – Nodestatus

    Indicates the node statusWhen PortID is empty then ALLnode status is returned

    R paramValue:2 – offline1 – online0 – Not registered

    -2 – Messagestatusrequest

    Request message status. Currentlythere is support for sending onepacket at a time. This commandreturns the status for this sending

    R paramValue:0)Tx_Buff_Empty1)Tx_Buff_Empty_TxSuccess, Bufferempty after last Tx transmition succedded(RTS received)2)Tx_Buff_Empty_TxRejected

    Buffer empty after last Tx transmitionfailed (Reject received)3)Tx_Buff_Empty_TxAbortedBuffer empty after last Tx transmition

    was aborted (Abort command send)4)Tx_Buff_Full

    3 – Tx Abort

    In case Tx buffer is still full, sendabort command is send to abort datatransmition

    W paramValue: PortID

    4 – Datapacket

    When sending data to a port, thepacket will indicate timeout after

    R/W paramValue:0x0000-0xFFFF

  • 8/9/2019 Sc14dectipbs Web API v1.3

    6/13

    April 10, 2012 v1.1 Dialog Semiconductor B.V. page 6 of 13

    SC14DECTIPBS

    WebAPI

    timeout [s] “Data packet timeout” seconds.When packet is not transmittedwithing this time, an Abort commandwill be send to CVM unit in order tocancel transmittion.

    5 – Nodecommunic

    ationtimeout [s]

    When no data has been receivedfrom a Node after “Node

    communication timeout” the port willbe considered offline. A write will setthe timeout value for the sensor, aread will return both this value, alongwith the elapsed time since thesensor was seen alive.

    R/W paramValue:0x0000-0xFFFF

    6 – Returndata

    Request to return data packets froma port stored in the receive buffer.Receiver buffer is 32 packet largecyclic buffer. Data will be returnedusing the Data Command. Usermust take care of tracking packId.Packid should match the latestpackID already read from a previousread command. Note: Refer to

    Appendix B for payload format.

    R paramValue:0 – Return all data1 – FF: return ALL data starting fromcorresponding packId.

    Use this command when interested for ahistory of received data, for example topost process values, create statistics,graphs,etc

    7- Nodetype

    Returns the sensor type for thegiven portID

    SENSOR_TYPE_NONE = 0x00SENSOR_TYPE_GENERIC =0x01

    ACTUATOR_TYPE_GENERIC = 2SENSOR_TYPE_BUTTON=0x14SENSOR_TYPE_TEMP=0x15SENSOR_TYPE_REDRELAIS=0x18TYPE_SWITCH_220=0x45

    8- Nodeattribute

    Returns the attribute value for agiven node. There are 4 attributesavailable per node. Attribute valuesare assigned from the userapplication which runs in the board.

    9 – Latestevent data

    Returns the latest packet stored fora given datatype (event). Data willbe returned using the DataCommand. Note: Refer to AppendixB for payload format.

    It is used when only interested for latestpackets. In contrast to paramID=6, thisone doesn’t require extra handling andparsing of returned data on the user sideto extract latest value.

    10 – IPEIread

    Returns the IPEI value of a sensor(unique 5 byte number). In contrastto portID number, IPEI value doesnot depend on registrationsequence.

    Examples:For every sensor ID get its status value:

    {"cmdType":1,"portId":{},"param":[{"paramId":1,"paramValue":{}}]}For sensor ID=7 get its status value:

    {"cmdType":1,"portId":7,"param":[{"paramId":1,"paramValue":{}}]}For every sensor ID get its type:

    {"cmdType":1,"portId": {},"param":[{"paramId":7,"paramValue":{}}]}For every sensor ID get before how many seconds an activity was recorded:

    {"cmdType":1,"portId": {},"param":[{"paramId":5,"paramValue":{}}]}For sensor ID=8 set timeout value:

    {"cmdType":1,"portId": 8,"param":[{"paramId":5,"paramValue":3600}]}For sensor ID=8 read its attribute value 0:

    {"cmdType":1,"portId": 8,"param":[{"paramId":8,"paramValue":0}]}

  • 8/9/2019 Sc14dectipbs Web API v1.3

    7/13

    April 10, 2012 v1.1 Dialog Semiconductor B.V. page 7 of 13

    SC14DECTIPBS

    WebAPI

    3. System command (“cmdType”: “2”):

    System commands are issued in the following format:{ “cmdType":"2","portId": {},“sysParamType”:””,”sysParamValue”:”” }

    Example:

    { "cmdType":2,"portId": {},"sysParamType":2,"sysParamValue":1}Fields are numbers.

    For write command this command returns:{"cmdType":2, errDesc":0} for SUCCESS{"cmdType":2, errDesc":Val} for FAIL. Error description is Val

    For read/request command this command returns:{"cmdType":2, errDesc":0, sysParamValue:,} for SUCCESS{"cmdType":2, errDesc": Val } for FAIL. Error description is Val

    NOTE: The portId parameter is included in the common command format, but is ignored in a system command. The DECTIP BS will return system commands with a b lank portId (blank array {}).

    When issuing a read request for a parameter an empty array is used, so the format shall be:“”:{} The parameter value will be returned by the DECT IP BS in the following format:{ “”:” ” }

    SysParamTypeValues

    Description Read /Write

    Comments

    0 – 3 Port parameters - See values below fordetails

    0 – Set registrationmode

    Enable/disable registration mode R/W paramValue: 1 – enableother – disable

    1 – Set access code Set or read the access PIN code for registratino R/W paramValue: 0x0000-0xFFFF

    2 – Deregisterdevice

    Delete registration of a sensor node.Use the configuration command to check status ofa port to double check if the node is deregistered.

    W paramValue:0x00 – 0xFF: portId tobe deregistered.

    3 – Get system time Returns the ULE system time in seconds R4- Read syslog File Returns a string with the board syslog file for

    remote debugging system status requestR

    5- Request buttonpress

    It returns 0 if user presses board button within 30sec, or else 1 for timeout. It can be used as part ofregistration/aunthedication process to requestuser physical interaction with the board.

    R

    6 – Request SWversion

    It returns an array of three 3 strings containing theSW version of the application, the stack andwhether it supports voice.Example for flat design and no VOIP:IPBASE_1_0_1_00018:NatalieV0711:VOIP_DISExample for CVM module design with VOIP:IPBASE_1_0_1_00018:CVMV0711:VOIP_EN

    R

    Examples:Read registration mode:{"cmdType":2,"portId": {},"sysParamType":0,"sysParamValue":{}}Set registration mode:

  • 8/9/2019 Sc14dectipbs Web API v1.3

    8/13

    April 10, 2012 v1.1 Dialog Semiconductor B.V. page 8 of 13

    SC14DECTIPBS

    WebAPI

    {"cmdType":2,"portId": {},"sysParamType":0,"sysParamValue":1}Read access code:{"cmdType":2,"portId": {},"sysParamType":1,"sysParamValue":{}}Read system time :{"cmdType":2,"portId": {},"sysParamType":3,"sysParamValue":{}}Degister device with ID = 8{"cmdType":2,"portId": {},"sysParamType":3,"sysParamValue":8}

    User command (“cmdType”: “3”):

    User commands are issued in the following format:{ “cmdType":"3"," UserAppData ”:”” }

    Example:

    { "cmdType":3," UserAppData ": {“user_parameter1”:123, “user_parameter2”:456, “user_parameter3”:789} }

    This command is used as a link between the web and a user application running in IP base station. The UserAppData field can contain any data in any format which the user defines to get interpreted in his application. On the IPS baseside the user in the main function during application Init registers the function he wants to execute when suchcommand is received by using the function ULE_UserWebReqHandler_CallBack. The result depends on theprocessing made in this function, as the web application gets exactly the JSON object which is returned from thisfunction. A typical usage example of this command is the ability to control through the network different options andparameters of the user application running in the IP base. For example, in the release demo this command is used topass the event-activities pairs that the user wants the IP base to run in the background.

  • 8/9/2019 Sc14dectipbs Web API v1.3

    9/13

    April 10, 2012 v1.1 Dialog Semiconductor B.V. page 9 of 13

    SC14DECTIPBS

    WebAPI

    4. VOIP conf iguration command (“cmdType”: “ 4”):

    VOIP configuration commands are issued in the following format:

    {"cmdType":4,"portId":","param":[{"paramId":,"paramValue": }, … }]}

    Or for a single paramID:

    {"cmdType":4,"portId":", “paramId":,"paramValue":}

    Example:

    {"cmdType":4,"portId": 1,"paramId":7,"paramValue":1}

    Fields are numbers and Param field is an array of JSON paramId/Paramvalue structure.

    For write command this command returns:

    {"cmdType":4,"portId":,errDesc": UleErrEnum }UleErrEnum : ULE_Success for success or else refer to APPENDIX A for error type

    For read/request command this command returns:

    {"cmdType":4,"portId":, errDesc":0, "paramId":, paramValue:} for SUCCESS

    {"cmdType":4,"portId":,"paramId":, errDesc": UleErrEnum } for FAIL. Refer to APPENDIX A forerror type

    When issuing a read request with portiD:{}, the response is gernerated for all available portID.Valid range for portID is from 1 to 6.

    When issuing a read request for a parameter an empty array is used, so the format shall be:“”:{}

    ParamIDValues Description Read /Write Comments

    1 – 8 Port parameters - See values below for details

    1 – Nodestatus

    Indicates the node statuswhen PortID is empty then ALL nodestatus is returned.

    R paramValue:1 – online0 – Not registered

    -7- Nodetype

    Returns the handset type for thegiven portID

    HANDSET_TYPE_NONE = 0x00HANDSET_TYPE_GENERIC = 0x0AHANDSET_TYPE_PENDANT = 0x0B

    8- Nodeattribute

    Returns the attribute value for agiven node. There are 4 attributes

    available per node. Attribute 0 forpendants holds any ALARM orEVENT indications.

    RW

    10 – IPEIread

    Returns the IPEI value of a sensor(unique 5 byte number). In contrastto portID number, IPEI value doesnot depend on registrationsequence.

    11 – Configure

    Retrieves/Set the number thependant will call when alarm button

    R/W

  • 8/9/2019 Sc14dectipbs Web API v1.3

    10/13

    April 10, 2012 v1.1 Dialog Semiconductor B.V. page 10 of 13

    SC14DECTIPBS

    WebAPI

    pendantdirect callnumber

    is pressed.

    12 – Configureringingmelody

    Retrieves/Set the ringing melody.Valid values are from 1 to 7

    R/W

    13 – Configureringingvolume

    Retrieves/Set the ringing volume.Valid values are from 0 -5

    R/W

    14 – Configurevibrationmode

    Retrieves/Set the Vibration mode.0 - Disabled1 - Enabled

    R/W

    15 – Configurespeechvolume

    Retrieves/ Set the speech volume.Valid values are from 0 -5

    R/W

  • 8/9/2019 Sc14dectipbs Web API v1.3

    11/13

    April 10, 2012 v1.1 Dialog Semiconductor B.V. page 11 of 13

    SC14DECTIPBS

    WebAPI

    APPENDIX A

    ErrDesc – UleErrEnum is

    0. ULE_Success, // Operation Succeed1. ULE_Fail, // ULE generic error

    2. ULE_InitFail, // ULE failed to initialize3. ULE_NotInitialized, // ULE is not initialized. Run ULE_Init first4. ULE_PP_OutOfRangeError, // Tried to access a portable device out of range: id > PP_COUNT_MAX (64)5. ULE_PP_AttrOutOfRangeError, // Tried to read an attribute value out of range MAXUSERATTRIB6. ULE_PP_BusTimeOutError, // SPI bus failed to initialize during ULE system Init7. ULE_AlreadyInitialized, // ULE sys is already initialized8. ULE_PP_Reserved2,9. ULE_PP_Reserved3,10. ULE_SetRegModeError, // Failed to set ULE registration mode11. ULE_PP_Reserved4,12. ULE_PP_SetCodeError, // Failed to set ULE access code13. ULE_PP_GetCodeError, // Failed to get ULE access code14. ULE_PP_NotRegisteredError, // ULE ID device in not registered15. ULE_Get_Registration_CountError, // Failed to read which devices are registered16. ULE_TxAbortError, // Failed to Abort TX data transmit17. ULE_TxBuffNoSpaceError, // Tx buffer is full18. ULE_CmdTypeFmtWrong, // Json string : Format of Cmdtype field is wrong19. ULE_IncorrectJsonInput, // Json string : Cannot parse Json string20. ULE_CmdTypeWrongValue, // Json string : cmd type field is out of range21. ULE_PortIdFmtWrong, // Json string : Format of portID field is wrong22. ULE_PackIdFmtWrong, // Json string : Format of PackID field is wrong23. ULE_DataFmtWrong, // Json string : Cannot read data field24. ULE_DataFmtTypeMismatch, // Json string : data field is not an array25. ULE_DataArrayTooLarge, // Json string : data field array is too large26. ULE_sysParamTypeFmtWrong, // Json string : SysParamType format error27. ULE_WriteOnly, // Json string : Can only write to property. Need to specify ParamValue28. ULE_sysParamTypeUnknown, // Json string : SysParamType is out of range29. ULE_ConfPortIdFmtWrong, // Json string : portID is not specified or is not a number30. ULE_ParamFmtWrong, // Json string : Need to specify parameter array

    31. ULE_ConfParamFmtIsnNotArray,// Json string : Need to specify parameter array32. ULE_ConfParamFmtArrayErr, // Json string : Need to specify parameter array33. ULE_ConfParamTypeFmtWrongID, // Json string : ParameterID is not specified34. ULE_sysParamTypeFmtWrongVal, // Json string : Parameter value is not specified35. ULE_NotImplemented, // Feature not implemented yet36. ULE_ReadOnly, //Json string : Can only read this attribute and not set37. ULE_ParamTypeUnknown, // Json string : Parameter ID is unknown38. ULE_DeregistrationError, // Failed to deregister device39. ULE_SensortypeoutOfRange, // User registers a function for a non valid sensor type40. ULE_DatatypeoutOfRange, // User registers a function for a non valid data type41. ULE_UserDataJSONOBJECTNotDefined, // JSON user command does not specify UserData field42. ULE_UserDatahandleFunctionNotDefined, // JSON user command handler function is not specified yet43. ULE_EarlyBitConfigurationInvalid, // JSON early send configuration bit is not 0,1 or 244. ULE_IPUIreadError, // Dect API failed to read IPUI

  • 8/9/2019 Sc14dectipbs Web API v1.3

    12/13

    April 10, 2012 v1.1 Dialog Semiconductor B.V. page 12 of 13

    SC14DECTIPBS

    WebAPI

    APPENDIX B

    Payload format

    A typical payload from/to a sensor is consisted of a maximum of 20 bytes. As described in theMmiUlePdu_common_t structure in the MmiFpPpCommon.h, it is consisted of the following bytes:

    rsuint8 Length; MmiDataType_t PayloadType; MmiUleSensHdr_t SensorType; rsuint8 NextMess; rsuint8 Data[16];

    Byte 1: Length: This is how many bytes exist in the payload.

    Byte 2: PayloadType: This byte is the payload data type. It defines the meaning of the Data[16] bytes.Typical values for this byte are described in the MmiDataType_t structure.

    Byte 3 sensor type: This is the type of the sensor that this message comes from/to. Typical values for this

    byte can be the following. Typical values for this byte are described in the MmiUleSensHdr_t structure.For the current release only a generic actuator and a generic button are implemented. Byte 4: Nextmessage: This byte indicates whether all the data information is included in this message orthere is going more to be padded in the next one. Byte 5-Byte 20: Data: 16 Bytes of data containing the information transmitted from/ to sensor. Forexample for a HAL data type (MMI_DATA_TYPE_HAL) the meaning of this field is defined by theMmiUleData_MmiDataTypeHal structure. For a wake up config data type(MMI_DATA_TYPE_WAKEUP_CFG ) the meaning of this field is defined by theMmiUleData_MmiDataTypeWakeupCfg structure.

    Each of those data structures may contain the UleAction field, which defines whether to read or writethe corresponding attribute value of the payload. For example in a switch with the following payloadformat:

    MmiUleAction_t Switch_Cmd_Action;rsuint8 Switch_Cmd; // 1 = On, 0 = Off rsuint8 DummyData[14];

    The Switch_Cmd byte is treated by the device as described by the first byte Switch_Cmd :

    IGNORE = 0, WRITE_ONCE = 1, WRITE_TO_NVS =2, READ = 3

    Therefore the portable device can send a message to the fixed part to indicate its current status bysending this payload:[49,69,0,3,STATUS]while the fixed part can set the value of an actuator ON/OFF by sending this payload to the portabledevice:[49,69,0,1,STATUS].

  • 8/9/2019 Sc14dectipbs Web API v1.3

    13/13

    April 10, 2012 v1.1 Dialog Semiconductor B.V. page 13 of 13

    SC14DECTIPBS

    WebAPI

    Appendix C

    Network / IP-BASE / DECT data flow

    This article here describes how data flows through the different components of the system by taking theexample in which user sends a JSON command to switch ON an actuator. A user does this by sending a

    [{"cmdType":0,"portId":7," EarlyBit": 1,"data":[49,69,0,1,1,0,0,0,0,0,0,0,0,0,0,0,0,0,0]}]

    Json command to IP base. The IP base replies back to the user with

    [{"cmdType":0,"errDesc":0}]

    indicating that the command was accepted (nothing was wrong with the parameters) and this message hasbeen scheduled to be send to the sensor. A positive reply back doesn’t mean that the message was actuallysend. The sensor may be sleeping at this time and may take minutes or even hours depending on the sleepcycle configuration of the sensor to wake up and receive the message. Considering that only one messageper sensor can be send at a time, the user has to check the status of transmit buffer by sending Tx statusrequest for the sensor:

    {"cmdType":1,"portId":7,"param":[{"paramId":2,"paramValue":{}}]}

    At this point the TX buffer will remain full until the sensor wakes up and receives the message, or themessage gets rejected for some reason by the DECT radio or the user explicitly decides to abort the currenttransmition and allow the sending of another higher priority payload:

    {"cmdType":1,"portId":7,"param":[{"paramId":3,"paramValue":{}}]}

    Now on the other way around, when a sensor sends a message back to IP BASE, the IP BASE will keepplacing the messages in a Receive cyclic buffer, one after the other, recording the timestamp in seconds andassigning an incremental packetID to each packet. This buffer is 32 packets large.Now the user has three options to read the data:

    1) By reading the Receive buffer through the JSON command (6 – Return data){"cmdType":1,"portId":7,"param":[{"paramId":6,"paramValue":0}]}

    User SW has to do the parsing regarding timestamps and packet IDs and every time send a new JSONcommand with updated ParamValue=LatestPacketID to filter out messages already read.This approach is encouraged to get used only if the user wants a history of the data, create graphs,statistics, or do other data processing.

    2) By reading sensor attribute values

    {"cmdType":1,"portId": 8,"param":[{"paramId":8,"paramValue":0}]}

    In IP base there is the user application which run and can act with minimum latency in any sensor event.This application can do any processing and pass information to the network though the "attributes"In this demo the SW software is simply written to pass the value of latest switch read to attribute 1.This method relies on user SW running in IP BASE to pass proper data to attribute values.

    3) By reading latest event data

    {"cmdType":1,"portId": 8,"param":[{"paramId":9,"paramValue":49}]}

    In most cases the user usually is interested for the latest data coming from a sensor of a given data type.Past values may be of no interest and likely there may be no attribute written by the user application to passlatest data. In the switch example datatype MMI_DATA_TYPE_SWITCH_220=49 gives the switch status,therefore the user can send the command above to get the latest packet of this data type received from thesensor and avoid option1 which requires extra effort on user side to do the necessary parsing.