Luup Protocol

Latest revision as of 08:24, 23 August 2013

[edit] Luup Request API

LuaUPnP's functionality is available through the Luup request api available here:Luup Requests

[edit] lu_sdata formatting

One of the most important requests is lu_sdata, which is explained in detail here:Luup Sdata

[edit] HTTP GET overview

• Arguments
  • Arguments to LuaUPnP API calls are formatted as Query strings and passed to the engine either on a LAN on port 3480 or through the MiOS forward servers. Requests take the form:

 <prefix>/data_request?id=<request>&field1=value1&field2=value2&...&fieldN=valueN

• URL Encoding
  • Anyone implementing automatic calls to the LuaUPnP( Herafter referred to as Luup ) API must take caution that all reserved characters are properly replaced with their percent-encoded counterparts per RFC 3986

[edit] JSON overview

• The standard format for data returned by Luup Request is Java script object notation, or JSON.
• This is only meant to be a brief review of json. A full specification is available at http://www.json.org
• Objects
  • An Object is an ordered set of name/value pairs.
  • Objects begin with the left curly brace or { character, and end with the } or right curly brace character.
  • the name/value pairs of objects are separated by commas.
  • names in objects are always JSON Strings(see section 1.2.6) array.
• Arrays
  • An array is an ordered collection of values.
  • An array begins with [ (left bracket) and ends with ] (right bracket). Values are separated by , (comma).
• Values
  • A value can be a string in double quotes, or a number, or true or false or null, or an object or an array. These structures can be nested.
• Numbers
  • Any valid decimal number is a valid json number
• Strings
  • Strings are sequences of characters wrapped in double quotes.
  • All characters are valid in strings except the “ and \ characters

[edit] XML Overview

• All data request can optionally return in XML format instead of JSON.
• For a full reference on XML please see http://www.w3.org/TR/REC-xml/

[edit] Locating the MiOS engine

• To initiate communications with the MiOS engine, a HTTP GET request needs to be made to https://sta1.mios.com/locator_json.php?username=<username>
• username is the user-supplied username for accessing MyMiOS services
• Return data
  • A JSON object with one key/value pair,
  • key: units
  • value: a JSON array containing a list of the units accessible from your ip address with the supplied username.
  • each unit has the following fields
    • serialNumber
      • a json string with the unique serial number of the unit.
    • FirmwareVersion
      • a json string with the build version of the MiOS software on the unit.
    • ipAddress
      • an optional paramater. If present, implies that the MiOS engine is on the same LAN as the client software and the client software should attempt local access before remote access.
    • name
      • A json string with a user-specified name for the unit
    • users
      • A json array containing json strings specifying the valid users for the unit
    • active_server
      • a json string containing the forward server that should be tried first to communicate with the unit
    • forwardServers
      • a json array containing json objects containing the following key/value pairs
        • hostName
          • a json string with the url of a valid forward server for communicating with this unit
        • primary
          • a json value containing either true or false. If true, this server is the primary server for communicating with the unit

[edit] Prefix

• Local access
  • When accessing a MiOS engine on the same subnet as the client application, the prefix takes the form:

 http://<ip_address>:3480

• • • ip_address is the ip address of the MiOS engine
• Remote access
  • When accessing the MiOS engine through the MiOS forward servers, the prefix takes the form:

 http[s]://<fwd_server>/<username>/<password>/<serial> 

• fwd_server
  • one of the servers specified in the forwardServers array
• username
  • a user-specified MyMiOS username
• password
  • user-specified password for the MyMiOS username
• serial
  • one of the serial numbers returned from locator_json
• If local access is available (if the ipAddress field exists for the specified unit and is not null), it should be attempted first. Otherwise, remote access with the primary forward server and then other forward servers should be attempted.
• Using HTTPS/SSL as the transport when using the MiOS forward servers is advisable as the user credentials are contained within the URL, and using SSL will ensure the entire HTTP request is secure and cannot be intercepted easily by third parties.