Skip to content

API

Jump to bottom Edit New page
BeholdMyGlory edited this page Mar 26, 2014 · 12 revisions

Översikt

--

  • JSON-API

  • Standardport: 4711

  • I stil med Hue-API:t

    • Olika URL:er beroende på funktion
    • POST och GET

  • Nödvändiga funktioner

    • Söka efter brygga
    • Lägga till brygga manuellt
    • Lista bryggor och lampor
    • Ändra lampor

Felmeddelanden

  • Response:

    {
  "state":        "error",
  "errorcode":    "ERROR_CODE",
  "errormessage": "human-readable error message"
}

Standardfelmeddenden

Felkod Meddelande Noter
NOT_UNICODE couldn't decode as UTF-8
INVALID_JSON invalid JSON
INVALID_FORMAT the JSON was in an unexpected format
NOT_IMPLEMENTED feature not implemented yet
NOT_LOGGED_IN user has not yet authenticated using /authenticate, or 'user' cookie was malformed Endast om require_password är true i config.json

Se https://github.com/smab/playhouse-lights/blob/master/src/errorcodes.py för komplett lista.

Om inget annat anges resulterar ett lyckat anrop i svaret {"state": "success"}.

Resurser

Detta är en lista över de resurser och metoder som lampservern tillhandahåller. API:t är inspirerat av REST. ? efter attributnamn betecknar valfritt attribut.

Strukturer definierade nedan refereras till bland de olika resursernas in- och utdata.

  <hue-state-ändring> = {
    "on?":             boolean (true/false),
    "bri?":            uint8   (0-255),
    "hue?":            uint16  (0-65535),
    "sat?":            uint8   (0-255),
    "xy?":             [0.0-1.0, 0.0-1.0],
    "ct?":             153-500,
    "alert?":          "none"/"select"/"lselect",
    "effect?":         "none"/"colorloop",
    "transitiontime?": uint16 (multipel av 100 ms, default: 4)
  }

POST /lights

Ändra state för lampor

  • Request:

    [
  {
    "x":      x-koordinat för lampa,
    "y":      y-koordinat för lampa,
    "delay?": tid i sekunder som float (dvs t.ex 1.0 för en sekund, 0.5 för 500 ms) som servern ska vänta innan den genomför ändringen,
    "change": <hue-state-ändring>
  },
  ...
]

  • Felmeddelanden: Inga för tillfället

POST /lights/all

Sätt alla lampor till ett visst state.

  • Request: <hue-state-ändring>
  • Felmeddelanden
    • INVALID_ATTRIBUTE
    • INVALID_VALUE

GET /bridges

Få en lista på metadata för alla anslutna bryggor (IP, mac, etc).

  • Request: innehållet i request-bodyn ignoreras

  • Response:

    {
  "state": success,
  "bridges": {
    [MAC]: {
      "ip":             ...,
      "username":       String (null om inget användarnamn satt),
      "valid_username": true/false,
      "lights":         int (-1 om valid_username är false)
    },
    ...
  }
}

POST /bridges/add

Lägg till brygga med IP (och potentiellt användarnamn).

  • Request: {"ip": ..., "username?": ...}

  • Response:

    {
  "state": "success",
  "bridges": {
    [MAC]: {
      "ip":             ...,
      "username":       String (null om inget användarnamn satt),
      "valid_username": true/false,
      "lights":         int (-1 om valid_username är false)
    }
  }
}

  • Felmeddelanden

    • BRIDGE_NOT_FOUND -- "couldn't find a Hue bridge at given address '{}'"
    • BRIDGE_ALREADY_ADDED -- "bridge has already been added to the server"

POST /bridges/save

Sparar nuvarande bryggkonfiguration (IP-adresser samt brygganvändarnamn). Konfigurationen läses sedan in igen nästa gång servern startar.

  • Request: innehållet i request-bodyn ignoreras
  • Response: {"state": "success"}

POST /bridges/add

Lägg till brygga med IP (och potentiellt användarnamn).

  • Request: {"ip": ..., "username?": ...}

  • Response:

    {
  "state": "success",
  "bridges": {
    [MAC]: {
      "ip":             ...,
      "username":       String (null om inget användarnamn satt),
      "valid_username": true/false,
      "lights":         int (-1 om valid_username är false)
    }
  }
}

  • Felmeddelanden

    • BRIDGE_NOT_FOUND -- "couldn't find a Hue bridge at given address '{}'"
    • BRIDGE_ALREADY_ADDED -- "bridge has already been added to the server"

POST /bridges/[MAC]

Ändra inställningar för brygga (främst användarnamn).

  • Request: {"username": ...}
  • Response: {"state": "success", "username": ..., "valid_username": true/false}
  • Felmeddelanden
    • NO_SUCH_MAC -- "the server does not know of a bridge with the MAC address '{mac}'"

DELETE /bridges/[MAC]

Säg åt servern att glömma en brygga.

  • Request: innehållet i request-bodyn ignoreras
  • Response: {"state": "success"}
  • Felmeddelanden
    • NO_SUCH_MAC

POST /bridges/[MAC]/lights

Ändra lampor för individuella bryggor.

  • Request: [{"light": nummer på lampan, "change": <hue-state-ändring>}, ...]
  • Response: {"state": "success"}
  • Felmeddelanden
    • NO_SUCH_MAC -- "the server does not know of a bridge with the MAC address '{mac}'"

POST /bridges/[MAC]/lights/all

Ändra alla lampor för en enskild brygga.

  • Request: <hue-state-ändring>
  • Response: {"state": "success"}
  • Felmeddelanden
    • NO_SUCH_MAC -- "the server does not know of a bridge with the MAC address 'mac'"

POST /bridges/[MAC]/adduser

Lägg till användare till brygga.

  • Request:

    {
  "username": sträng med 10-40 tecken. Denna parameter är valfri, om
              man inte har med denna parameter autogenereras en
              slumpmässig nyckel.
}

  • Response: {"state": "success", “username”: nya användarnamnet}

POST /bridges/[MAC]/lampsearch

Lägg till nya lampor till brygga. För att denna operation ska fungera måste länkknappen på bryggan tryckas.

  • Request: innehållet i request-bodyn ignoreras
  • Response: {"state": "success"}

POST /bridges/search

Sätt igång UPnP-discovery (asynkron). Om auto_add är true läggs de funna bryggorna också till till serverns interna brygglista (d.v.s. det är ej nödvändigt att anropa /bridges/add manuellt).

  • Request: {"auto_add": boolean}
  • Response: {"state": "success"}
  • Felmeddelanden
    • CURRENTLY_SEARCHING -- "currently searching for bridges"

GET /bridges/search

Hämta resultat från UPnP-discovery. om /bridges/search ej har anropats ännu kommer "bridges" att vara en tom map.

  • Request: innehållet i request-bodyn ignoreras
  • Response: {"state": "success", "bridges": {mac1: ip1, mac2: ip2, ...}}
  • Felmeddelanden
    • CURRENTLY_SEARCHING

GET /grid

Hämtar ut nuvarande lampgrid

  • Request: innehållet i request-bodyn ignoreras

  • Response:

    {
  "state": "success",
  "width": int,
  "height": int,
  "grid": [
    [
      {"mac": String (MAC-adress för bryggan lampan är associerad med), "lamp": int (ID:t för lampan på bryggan)},
      ...
    ],
  ...
  ]
}

POST /grid

Ersätter nuvarande lampgrid

  • Request: En tvådimensionell array som motsvarar rutnätet, se "grid"-attributet i svaret till GET /grid för format
  • Response: {"state": "success"}

POST /grid/save

Sparar nuvarande gridkonfiguration (varje lampa och vilken x/y-position, brygga, och lampnummer på bryggan som den är associerad med). Konfigurationen läses sedan in igen nästa gång servern startar.

  • Request: innehållet i request-bodyn ignoreras
  • Response: {"state": "success"}

GET /status

Returnerar alltid 200 OK

  • Request: innehållet i request-bodyn ignoreras
  • Response: respons-bodyn är tom

POST /authenticate

Returnerar, om lösenordet överensstämmer med det som listas i config.json, en kaka med namnen 'user' i HTTP-headerserna ('Set-Cookie'-headern) som måste skickas med i HTTP-requests ('Cookie'-headern) till övriga metoder. username ignoreras för tillfället, men kommer att vara innehållet i 'user'-kakan.

  • Request: {"password": ..., "username": ...}
  • Response: {"state": "success"}
  • Felmeddelanden
    • AUTH_NOT_ENABLED
    • INVALID_PASSWORD
Add a custom footer
Add a custom sidebar
Clone this wiki locally