{"metadata":{"image":[],"title":"","description":""},"api":{"url":"","auth":"required","params":[],"results":{"codes":[]},"settings":""},"next":{"description":"","pages":[]},"title":"Device Messages","type":"basic","slug":"device-messages","excerpt":"","body":"Device messages control and acquire the state of a device, independent of its specific type. The state is composed of the [label](#section-label), [port](#section-port), [power level](#section-power-level), [time](#section-time), firmware version and microcontroller statistics.\n\nThese messages are common to all LIFX devices, which may also implement device specific messages, such as [Light Messages](doc:light-messages).\n\nThe [Protocol header](doc:header-description#protocol-header) _message type_ field value (decimal) appears after each message name in this document. Each section below describes the _payload_ that is appended to the [message header](doc:header-description#message-header). Some messages do not require a payload.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Enumerated Types\"\n}\n[/block]\n# Service\n\nDescribes the services exposed by the device.\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Type\",\n    \"h-1\": \"Value\",\n    \"0-0\": \"UDP\",\n    \"0-1\": \"1\"\n  },\n  \"cols\": 2,\n  \"rows\": 1\n}\n[/block]\nWhen a device is [discovered](doc:workflow-diagrams#discovery) the Service types and IP [port](#section-port) are provided.\n\nAll values other than those documented above are reserved for future protocol expansion.\n\nThe LIFX Protocol utilizes UDP/IP for all messages covered by this documentation.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Message Field Data Types\"\n}\n[/block]\n# Labels\nFor user interfaces purposes, each device can be identified by their _label_ as well as a group and a location.\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Field\",\n    \"h-1\": \"Type\",\n    \"0-0\": \"label\",\n    \"0-1\": \"string, size: 32 bytes\"\n  },\n  \"cols\": 2,\n  \"rows\": 1\n}\n[/block]\nThe _label_ string is a fixed-length field, which is __not__ null-terminated.\n\nIf you are setting a label/group/location for your light, it is highly recommended you store the label as a utf-8 string for compatibility with existing clients.\n\n# Port\nThe IP port number used by a LIFX device for a specific [Service](#section-service).\n\n| Field | Type |\n|-----|------|\n| port | unsigned 32-bit integer |\n\nWhilst LIFX devices usually listen to port 56700, it is strongly recommended that devices are discovered and the provided port number is used.\n\nAs of LIFX Protocol V2, LIFX devices sending unicast message responses will reply to whichever port number the client has bound. See [message header frame source identifier](doc:header-description#frame) regarding the conditions under which unicast messages are sent.\n\nPrior to LIFX Protocol V2, i.e the Original LIFX A21 lightbulb running firmware version 1.x, LIFX devices send broadcast message responses to port 56700.\n\nTo get the best compatibility across both newer and older LIFX devices, clients should bind to UDP port 56700.\n\n### Power level\n\nThe _power level_ can be either standby (0) or enabled (65535).\n\n| Field | Type |\n|-------|------|\n| level | unsigned 16-bit integer |\n\nCurrently, only the values 0 and 65535 are supported\n\n### Time\n\nAll _time_ values have a precision of nanoseconds. When an absolute time value is provided, then it is the number of nanoseconds since the [epoch](http://en.wikipedia.org/wiki/Unix_time), i.e Thursday 1st January 1970 00:00:00.\n\n| Field | Type |\n|-----|------|\n| time | unsigned 64-bit integer |\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Device Messages\"\n}\n[/block]\n### GetService - 2\n\nSent by a client to acquire responses from all devices on the local network. No payload is required. Causes the devices to transmit a [StateService](#section-stateservice-3) message.\n\nWhen using this message the [Frame](doc:header-description#frame) _tagged_ field must be set to one (1).\n\n### StateService - 3\n\nResponse to [GetService](#state-getservice-2) message.\n\nProvides the device [Service](#section-service) and [port](#section-port). If the Service is temporarily unavailable, then the _port_ value will be 0.\n\n| Field | Type |\n|-----|------|\n| service | unsigned 8-bit integer, maps to [Service](#section-service) |\n| port | unsigned 32-bit integer |\n\n### GetHostInfo - 12\n\nGet Host MCU information. No payload is required. Causes the device to transmit a [StateHostInfo](#section-statehostinfo-13) message.\n\n### StateHostInfo - 13\n\nResponse to [GetHostInfo](#state-gethostinfo-12) message.\n\nProvides host MCU information.\n\n* signal: radio receive signal strength in milliWatts\n* tx: bytes transmitted since power on\n* rx: bytes received since power on\n\n| Field | Type |\n|-------|------|\n| signal | 32-bit float |\n| tx | unsigned 32-bit integer |\n| rx | unsigned 32-bit integer |\n| reserved | signed 16-bit integer |\n\n### GetHostFirmware - 14\n\nGets Host MCU firmware information. No payload is required. Causes the device to transmit a [StateHostFirmware](#section-statehostfirmware-15) message.\n\n### StateHostFirmware - 15\n\nResponse to [GetHostFirmware](#section-gethostfirmware-14) message.\n\nProvides host firmware information.\n\n* build: firmware build [time](#section-time) (absolute time in nanoseconds since epoch)\n* version: firmware version\n\n| Field | Type |\n|-------|------|\n| build | unsigned 64-bit integer |\n| reserved | unsigned 64-bit integer |\n| version_minor | unsigned 16-bit integer |\n| version_major | unsigned 16-bit integer |\n\n### GetWifiInfo - 16\n\nGet Wifi subsystem information. No payload is required. Causes the device to transmit a [StateWifiInfo](#section-statewifiinfo-17) message.\n\n### StateWifiInfo - 17\n\nResponse to [GetWifiInfo](#section-getwifiinfo-16) message.\n\nProvides Wifi subsystem information.\n\n* signal: radio receive signal strength in mw or signal to noise ratio\n* tx: bytes transmitted since power on\n* rx: bytes received since power on\n\n| Field | Type |\n|-------|------|\n| signal | 32-bit float |\n| tx | unsigned 32-bit integer |\n| rx | unsigned 32-bit integer |\n| reserved | signed 16-bit integer |\n\nNote that while most of our products report wifi rssi in the signal property, some products will report signal to noise ratio. The following code can be used to determine the strength of the wifi signal from this value:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"import math\\n\\nsignal = \\\"[value from the StateWifiInfo.Signal property]\\\"\\n\\nval = math.floor(10 * math.log10(signal) + 0.5)\\n\\nif val < 0 or val == 200:\\n    # The value is wifi rssi\\n\\n    if val == 200:\\n        return \\\"No signal\\\"\\n    elif val <= -80:\\n        return \\\"Very bad signal\\\"\\n    elif val <= -70:\\n        return \\\"Somewhat bad signal\\\"\\n    elif val < -60:\\n        return \\\"Alright signal\\\"\\n    else:\\n        return \\\"Good signal\\\"\\nelse:\\n    # The value is signal to noise ratio\\n    \\n    if val == 4 or val == 5:\\n        return \\\"Very bad signal\\\"\\n    elif val >= 7 and val <= 11:\\n        return \\\"Somewhat bad signal\\\"\\n    elif val >= 12 and val <= 16:\\n        return \\\"Alright signal\\\"\\n    elif val > 16:\\n        return \\\"Good signal\\\"\\n    else:\\n        return \\\"No signal\\\"\",\n      \"language\": \"python\"\n    }\n  ]\n}\n[/block]\n### GetWifiFirmware - 18\n\nGet Wifi subsystem firmware. No payload is required. Causes the device to transmit a [StateWifiFirmware](#section-statewififirmware-19) message.\n\n### StateWifiFirmware - 19\n\nResponse to [GetWifiFirmware](#section-getwififirmware-18) message.\n\nProvides Wifi subsystem information.\n\n* build: firmware build [time](#section-time) (absolute time in nanoseconds since epoch)\n* version: firmware version\n\n| Field | Type |\n|-------|------|\n| build | unsigned 64-bit integer |\n| reserved | unsigned 64-bit integer |\n| version_minor | unsigned 16-bit integer |\n| version_major | unsigned 16-bit integer |\n\n### GetPower - 20\n\nGet device [power level](#section-power-level). No payload is required. Causes the device to transmit a [StatePower](#section-statepower-22) message.\n\n### SetPower - 21\n\nSet device [power level](#section-power-level). \n\nZero implies standby and non-zero sets a corresponding power draw level. Currently only 0 and 65535 are supported.\n\n| Field | Type |\n|-------|------|\n| level | unsigned 16-bit integer |\n\n### StatePower - 22\n\nResponse to [GetPower](#section-getpower-20) message.\n\nProvides device [power level](#section-power-level).\n\n| Field | Type |\n|-------|------|\n| level | unsigned 16-bit integer |\n\n### GetLabel - 23\n\nGet device [label](#section-label). No payload is required. Causes the device to transmit a [StateLabel](#section-statelabel-25) message.\n\n### SetLabel - 24\n\nSet the device [label](#section-label) text.\n\n| Field | Type |\n|-------|------|\n| label | string, size: 32 bytes |\n\n### StateLabel - 25\n\nResponse to [GetLabel](#section-getlabel-23) message.\n\nProvides device [label](#section-label).\n\n| Field | Type |\n|-------|------|\n| label | string, size: 32 bytes |\n\n### GetVersion - 32\n\nGet the hardware version. No payload is required. Causes the device to transmit a [StateVersion](#section-stateversion-33) message.\n\n### StateVersion - 33\n\nResponse to [GetVersion](#section-getversion-32) message.\n\nProvides the hardware version of the device. See  [LIFX Products](doc:lifx-products) for how to interpret the vendor and product ID fields.\n\n* vendor: vendor ID\n* product: product ID\n* version: hardware version\n\n| Field | Type |\n|-------|------|\n| vendor | unsigned 32-bit integer |\n| product | unsigned 32-bit integer |\n| version | unsigned 32-bit integer |\n\n### GetInfo - 34\n\nGet run-time information. No payload is required. Causes the device to transmit a [StateInfo](#section-stateinfo-35) message.\n\n### StateInfo - 35\n\nResponse to [GetInfo](#section-getinfo-34) message.\n\nProvides run-time information of device.\n\n* time: current [time](#section-time) (absolute time in nanoseconds since epoch)\n* uptime: [time](#section-time) since last power on (relative time in nanoseconds)\n* downtime: last power off period, 5 second accuracy (in nanoseconds)\n\n| Field | Type |\n|-------|------|\n| time | unsigned 64-bit integer |\n| uptime | unsigned 64-bit integer |\n| downtime | unsigned 64-bit integer |\n\n### Acknowledgement - 45\n\nResponse to any message sent with _ack\\_required_ set to 1. See [message header frame address](doc:header-description#frame-address).\n\n### GetLocation - 48\n\nAsk the bulb to return its location information.\nNo payload is required.\nCauses the device to transmit a [StateLocation](statelocation---50) message.\n\n### SetLocation - 49\n\nSet the device location.\n\nApplications wishing to change either the label or location attributes MUST set the `updated_at` field to the current timestamp and send the message to all applicable devices that are currently online. This is because when reading these values the applications will consider unique `location` fields to be a location identifier, and the label on the bulb with the highest `updated_at` field for that location will be used. Applications SHOULD attempt to correct any `label`s that are out of date when found.\nIt is recommended to set the response_required flag on the message header to speed up updating the cloud account.\n\nWhen creating a new location generate the `location` field with random data.\n\n* location: guid byte array.\n* label: text label for location.\n* updated_at: UTC timestamp of last label update in nanoseconds.\n\n| Field | Type |\n|-------|------|\n| location | byte array, size: 16 |\n| label | string, size: 32 |\n| updated_at | integer, size: 64 |\n\n### StateLocation - 50\n\nDevice location.\n\n| Field | Type |\n|-------|------|\n| location | byte array, size: 16 bytes |\n| label | string, size: 32 bytes |\n| updated_at | unsigned 64-bit integer |\n\n### GetGroup - 51\n\nAsk the bulb to return its group membership information.\nNo payload is required.\nCauses the device to transmit a [StateGroup](stategroup---53) message.\n\n### SetGroup - 52\n\nSet the device group.\n\nApplications wishing to change either the label or group attributes MUST set the `updated_at` field to the current timestamp and send the message to all applicable devices that are currently online. This is because when reading these values the applications will consider unique `group` fields to be a group identifier, and the label on the bulb with the highest `updated_at` field for that group will be used. Applications SHOULD attempt to correct any `label`s that are out of date when found.\nIt is recommended to set the response_required flag on the message header to speed up updating the cloud account.\n\nWhen creating a new group generate the `group` field with random data.\n\n* group: guid byte array.\n* label: text label for group.\n* updated_at: UTC timestamp of last label update in nanoseconds.\n\n| Field | Type |\n|-------|------|\n| group | byte array, size: 16 |\n| label | string, size: 32 |\n| updated_at | integer, size: 64 |\n\n### StateGroup - 53\n\nDevice group.\n\n| Field | Type |\n|-------|------|\n| group | byte array, size: 16 bytes |\n| label | string, size: 32 bytes |\n| updated_at | unsigned 64-bit integer |\n\n### EchoRequest - 58\n\nRequest an arbitrary payload be echoed back. Causes the device to transmit an [EchoResponse](#section-echoresponse-59) message.\n\n| Field | Type |\n|-------|------|\n| payload | byte array, size: 64 bytes |\n\n### EchoResponse - 59\n\nResponse to [EchoRequest](#section-echorequest-59) message.\n\nEcho response with payload sent in the EchoRequest.\n\n| Field | Type |\n|-------|------|\n| payload | byte array, size: 64 bytes |","updates":["57e4ce6ff3d7fc0e009c505d","59b63ab438283f00102a2d1c","5d49321a7f06e40011ed716d"],"order":1,"isReference":false,"hidden":false,"sync_unique":"","link_url":"","link_external":false,"_id":"57fdb17c4defec0e00642293","__v":2,"user":"557e2561eb75d80d00af3dab","category":{"sync":{"isSync":false,"url":""},"pages":[],"title":"Protocol Messages","slug":"message-types","order":3,"from_sync":false,"reference":false,"_id":"57fdb17c4defec0e0064228e","project":"5581248904ae5b0d0026289a","__v":0,"version":"57fdb17c4defec0e0064228b","createdAt":"2015-06-18T03:15:52.144Z"},"createdAt":"2015-06-18T03:18:57.998Z","githubsync":"","project":"5581248904ae5b0d0026289a","version":{"version":"2.0","version_clean":"2.0.0","codename":"","is_stable":true,"is_beta":false,"is_hidden":false,"is_deprecated":false,"categories":["57fdb17c4defec0e0064228c","57fdb17c4defec0e0064228d","57fdb17c4defec0e0064228e","57fdb520bcc07b0e00d1ef41"],"_id":"57fdb17c4defec0e0064228b","project":"5581248904ae5b0d0026289a","__v":2,"createdAt":"2016-10-12T03:43:56.009Z","releaseDate":"2016-10-12T03:43:56.009Z"},"parentDoc":null}