Provisioning defnes the process of connecting the Insert to the correct WiFi Network.

This process is can be handled by connecting to the device's WiFi Network (Swidget-XXXXXXXXXXXX) and navigating to the webpage https://10.123.45.1/provision.

The following description can be used to create a provisioning tool.

This is done via a 2-step process:

Send WiFi Credentials, along with an optional pre-defined Security Key
Query for connection status

The client must begin by connecting to the Insert's WiFi Hotspot, and from there can issue HTTPS requests to 10.123.45.1:443.

This process is broken into an asyncronous request to account for the channel-changing that is required when scanning for the SSID. Client devices are not necessarly capable of moving through the channels while maintaining a TCP connection to the device.

When the SSID credentials are sent to the device, a \"Secret Key\" will be returned, which will then be used as an Authorization token on all following requests. This \"Secret Key\" can also be set via an additional arguement in the request body defining the Secret Key to use.

Once the SSID credentials have been passed, poll for the network status:

NotInitiated - No connect request has been made
AttemptingConnect - Currently Attempting to connect

Success - Connect was successful
AuthFail - Incorrect PSK
SSIDNotFound - Could not find SSID (must be 2.4Ghz)
NoIpReceived - Failed to receive an IP, router must perform DHCP
FailedToConnect - Failed to connect to router

In the case of a successful connection, the insert will also return its IP and MAC address along with this response.

Once the Insert has connected, it will stop broadcasting a WiFi hotspot (After 2 minutes), and will being broadcasting for discovery and accepting HTTPS requests over the local WiFi network.

The Provisioning Request can also be used to set a Static IP, and to disable the authentication requirement. In order to use the HTTP functions, the authentication requirement must be disabled.

\n","event":[{"listen":"prerequest","script":{"id":"c6159f14-93c6-4e1d-838f-6d5745e38be0","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"ec8b5270-a096-452d-8cb0-a20d168792c3","type":"text/javascript","exec":[""]}}],"_postman_id":"8c88b02d-1d07-4ac4-875e-cf455c825aa1"},{"name":"Discovery","item":[],"id":"461fdc2a-f862-4a74-8c0e-2ebd6933de63","description":"

Discovery refers to the process of finding the Swidget Device within your network.

Swidget Inserts provide 2 means of Discovery

Control4's SDDP
Notify Alive

\nNOTIFY ALIVE SDDP/1.0\nFrom: \"192.168.0.33:1902\"\nHost: \"d8a01d69f874\"\nMax-Age: 1800\nType: \"Swidget\"\nPrimary-Proxy: \"swidget_driver\"\nProxies: \"swidget_driver\"\nManufacturer: \"Swidget\"\nModel: \"outlet/control\"\nDriver: \"swidget_driver.c4z\"\n

\nSearch Response

\nSDDP/1.0 200 OK\nFrom: \"192.168.0.33:1902\"\nHost: \"d8a01d69f874\"\nMax-Age: 1800\nType: \"Swidget\"\nPrimary-Proxy: \"swidget_driver\"\nProxies: \"swidget_driver\"\nManufacturer: \"Swidget\"\nModel: \"outlet/control\"\nDriver: \"swidget_driver.c4z\"

SSDP
Notify Example

\nNOTIFY * HTTP/1.1\nHOST: 239.255.255.250:1900\nNTS: ssdp:alive\nCACHE-CONTROL: max-age=1200\nSERVER: Swidget/1.0 outlet+control/1.2.23\nUSN: uuid:1d691134-b28c-44f1-b162-d8a01d69f874\nNT: urn:swidget:pico:1\nLOCATION: https://192.168.0.33:443\n

\nSearch Response

\nHTTP/1.1 200 OK\nEXT:\nCACHE-CONTROL: max-age=1200\nSERVER: Swidget/1.0 outlet+control/1.2.23\nUSN: uuid:1d691134-b28c-44f1-b162-d8a01d69f874\nST: urn:swidget:pico:1\nLOCATION: https://192.168.0.33:443\n

Description's of these discovery protocols is beyond the scope of this document.

\n","event":[{"listen":"prerequest","script":{"id":"356bbc65-d7cf-4ac3-b79b-96d4314e43d4","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"81d33ad5-0a1b-4e36-ba13-121b572e57d9","type":"text/javascript","exec":[""]}}],"_postman_id":"461fdc2a-f862-4a74-8c0e-2ebd6933de63"},{"name":"Device Control","item":[{"name":"Info","item":[{"name":"HTTPS Get Summary","id":"a10fc26a-830e-4f90-839b-193d9059e70c","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"x-secret-key","value":"Secret Key","type":"text"}],"url":"https://IP_ADDRESS/api/v1/summary","urlObject":{"protocol":"https","path":["api","v1","summary"],"host":["IP_ADDRESS"],"query":[],"variable":[]}},"response":[{"id":"7e0d601c-1a71-4d6e-8112-cfb9d61ac247","name":"Get Summary - Control + Outlet","originalRequest":{"method":"GET","header":[{"key":"x-secret-key","value":"Secret Key","type":"text"}],"url":"https://IP_ADDRESS/api/v1/summary"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Access-Control-Allow-Origin","value":"*"},{"key":"Access-Control-Allow-Headers","value":"x-secret-key"},{"key":"Content-Type","value":"application/json"},{"key":"Connection","value":"keep-alive"},{"key":"Content-Length","value":"258"}],"cookie":[],"responseTime":null,"body":"{\n \"model\": \"HK_PICO_1\",\n \"mac\": \"d8a01d69f874\",\n \"version\": \"1.2.23\",\n \"host\": {\n \"id\": \"un50gnpfEJ7yx88F1C6y\",\n \"type\": \"outlet\",\n \"error\": 0,\n \"components\": [\n {\n \"id\": \"0\",\n \"functions\": [\n \"power\",\n \"toggle\"\n ]\n },\n {\n \"id\": \"1\",\n \"functions\": [\n \"power\"\n ]\n }\n ]\n },\n \"insert\": {\n \"type\": \"control\",\n \"components\": []\n }\n}"},{"id":"ac9aceac-485d-41de-b35e-a24291ca9d01","name":"Get Summary - Temp Humi Motion + Dimmer","originalRequest":{"method":"GET","header":[{"key":"x-secret-key","value":"Secret Key","type":"text"}],"url":"https://IP_ADDRESS/api/v1/summary"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Access-Control-Allow-Origin","value":"*"},{"key":"Access-Control-Allow-Headers","value":"x-secret-key"},{"key":"Content-Type","value":"application/json"},{"key":"Connection","value":"keep-alive"},{"key":"Content-Length","value":"363"}],"cookie":[],"responseTime":null,"body":"{\n \"model\": \"HK_PICO_1\",\n \"mac\": \"500291a26d70\",\n \"version\": \"1.2.23\",\n \"host\": {\n \"id\": \"303DFFA7204839575151\",\n \"type\": \"dimmer\",\n \"error\": 0,\n \"components\": [\n {\n \"id\": \"0\",\n \"functions\": [\n \"power\",\n \"level\",\n \"toggle\"\n ]\n }\n ]\n },\n \"insert\": {\n \"type\": \"TEMP HUMI MOTION\",\n \"components\": [\n {\n \"id\": \"temp\",\n \"functions\": [\n \"temperature\"\n ]\n },\n {\n \"id\": \"humi\",\n \"functions\": [\n \"humidity\"\n ]\n },\n {\n \"id\": \"motion\",\n \"functions\": [\n \"occupied\"\n ]\n }\n ]\n }\n}"},{"id":"b83d857b-f38f-4d0c-b5b3-51d25d7d7cb5","name":"Get Summary - Fan (IB160)","originalRequest":{"method":"GET","header":[{"key":"x-secret-key","value":"Secret Key","type":"text"}],"url":"https://IP_ADDRESS/api/v1/summary"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Access-Control-Allow-Origin","value":"*"},{"key":"Access-Control-Allow-Headers","value":"x-secret-key"},{"key":"Content-Type","value":"application/json"},{"key":"Connection","value":"keep-alive"},{"key":"Content-Length","value":"363"}],"cookie":[],"responseTime":null,"body":"{\n \"model\": \"FAN_PICO_S3\",\n \"mac\": \"68b6b3303b94\",\n \"version\": \"1.6.40\",\n \"firmware\": {\n \"tag\": \"random\"\n },\n \"insert\": {\n \"type\": \"control\",\n \"components\": []\n },\n \"host\": {\n \"id\": \"3pg7snqu7BbjByyj6r7n\",\n \"type\": \"pesna_IB160\",\n \"error\": 0,\n \"components\": [\n {\n \"id\": \"0\",\n \"functions\": [\n \"power\",\n \"toggle\",\n \"dutyCycle\",\n \"exhaust\",\n \"supply\",\n \"mode\",\n \"boost\",\n \"error\",\n \"raw\",\n \"outdoors\",\n \"indoors\"\n ],\n \"maxCFM\": 160,\n \"code\": \"7040\"\n }\n ]\n }\n}"}],"_postman_id":"a10fc26a-830e-4f90-839b-193d9059e70c"},{"name":"HTTPS Get Name","id":"14a387ac-ad15-4281-91cf-be0fcea6d641","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"x-secret-key","value":"Secret Key","type":"text"}],"url":"https://IP_ADDRESS/api/v1/name","urlObject":{"protocol":"https","path":["api","v1","name"],"host":["IP_ADDRESS"],"query":[],"variable":[]}},"response":[{"id":"8c1a48ef-4f6e-4548-b009-e0fa3ef3456e","name":"Get State - Control + Outlet","originalRequest":{"method":"GET","header":[{"key":"x-secret-key","value":"Secret Key","type":"text"}],"url":"https://IP_ADDRESS/api/v1/state"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Access-Control-Allow-Origin","value":"*"},{"key":"Access-Control-Allow-Headers","value":"x-secret-key"},{"key":"Content-Type","value":"application/json"},{"key":"Connection","value":"keep-alive"},{"key":"Content-Length","value":"168"}],"cookie":[],"responseTime":null,"body":"{\n \"insert\": {\n \"components\": {}\n },\n \"host\": {\n \"components\": {\n \"0\": {\n \"toggle\": {\n \"state\": \"on\"\n },\n \"power\": {\n \"current\": 0,\n \"avg\": 0,\n \"avgOn\": 0\n }\n },\n \"1\": {\n \"power\": {\n \"current\": 0,\n \"avg\": 0,\n \"avgOn\": 0\n }\n }\n }\n }\n}"}],"_postman_id":"14a387ac-ad15-4281-91cf-be0fcea6d641"},{"name":"HTTPS Get State","id":"4668e273-436e-4de6-a408-944a95a541ca","protocolProfileBehavior":{"disableBodyPruning":true,"disabledSystemHeaders":{"connection":true}},"request":{"method":"GET","header":[{"key":"x-secret-key","value":"Secret Key","type":"text"},{"key":"Connection","value":"close","type":"text"}],"url":"https://IP_ADDRESS/api/v1/state","urlObject":{"protocol":"https","path":["api","v1","state"],"host":["IP_ADDRESS"],"query":[],"variable":[]}},"response":[{"id":"aed7720b-b70b-4654-87c1-2049850f9222","name":"Get State - Temp Humi Motion + Dimmer","originalRequest":{"method":"GET","header":[{"key":"x-secret-key","value":"Secret Key","type":"text"}],"url":"https://IP_ADDRESS/api/v1/state"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Access-Control-Allow-Origin","value":"*"},{"key":"Access-Control-Allow-Headers","value":"x-secret-key"},{"key":"Content-Type","value":"application/json"},{"key":"Connection","value":"keep-alive"},{"key":"Content-Length","value":"278"}],"cookie":[],"responseTime":null,"body":"{\n \"insert\": {\n \"components\": {\n \"temp\": {\n \"temperature\": {\n \"now\": 23.20302\n }\n },\n \"humi\": {\n \"humidity\": {\n \"now\": 28.86798\n }\n },\n \"motion\": {\n \"occupied\": {\n \"state\": true,\n \"secondsInState\": 340\n }\n }\n }\n },\n \"host\": {\n \"components\": {\n \"0\": {\n \"toggle\": {\n \"state\": \"on\"\n },\n \"level\": {\n \"now\": 20\n },\n \"power\": {\n \"current\": 0,\n \"avg\": 0,\n \"avgOn\": 0\n }\n }\n }\n }\n}"},{"id":"9c6cf733-ad4f-4950-afeb-0fac86460e1b","name":"Get State - Control + Outlet","originalRequest":{"method":"GET","header":[{"key":"x-secret-key","value":"Secret Key","type":"text"}],"url":"https://IP_ADDRESS/api/v1/state"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Access-Control-Allow-Origin","value":"*"},{"key":"Access-Control-Allow-Headers","value":"x-secret-key"},{"key":"Content-Type","value":"application/json"},{"key":"Connection","value":"keep-alive"},{"key":"Content-Length","value":"168"}],"cookie":[],"responseTime":null,"body":"{\n \"insert\": {\n \"components\": {}\n },\n \"host\": {\n \"components\": {\n \"0\": {\n \"toggle\": {\n \"state\": \"on\"\n },\n \"power\": {\n \"current\": 0,\n \"avg\": 0,\n \"avgOn\": 0\n }\n },\n \"1\": {\n \"power\": {\n \"current\": 0,\n \"avg\": 0,\n \"avgOn\": 0\n }\n }\n }\n }\n}"},{"id":"994232fb-b543-4abd-99ed-31bec7588ec3","name":"Get State - Fan (IB160)","originalRequest":{"method":"GET","header":[{"key":"x-secret-key","value":"Secret Key","type":"text"}],"url":"https://IP_ADDRESS/api/v1/state"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Access-Control-Allow-Origin","value":"*"},{"key":"Access-Control-Allow-Headers","value":"x-secret-key"},{"key":"Content-Type","value":"application/json"},{"key":"Connection","value":"keep-alive"},{"key":"Content-Length","value":"168"}],"cookie":[],"responseTime":null,"body":"{\n \"insert\": {\n \"components\": {},\n \"errors\": {\n \"self_diag\": 0\n }\n },\n \"host\": {\n \"components\": {\n \"0\": {\n \"toggle\": {\n \"state\": \"off\"\n },\n \"power\": {\n \"current\": 3,\n \"avg\": 2,\n \"avgOn\": 16.96\n },\n \"dutyCycle\": {\n \"minutes\": 0\n },\n \"exhaust\": {\n \"cfm\": 0,\n \"allowed\": [\n 0,\n 160\n ]\n },\n \"supply\": {\n \"cfm\": 0,\n \"allowed\": [\n 0,\n 160\n ]\n },\n \"mode\": \"heatExchange\",\n \"status\": \"normal\",\n \"speed\": \"low\",\n \"boost\": {\n \"mode\": \"off\",\n \"minutes\": 60\n },\n \"error\": {},\n \"indoors\": {},\n \"outdoors\": {},\n \"filter\": {\n \"needsReplacement\": false,\n \"needsCleaning\": false\n }\n }\n }\n },\n \"connection\": {\n \"rssi\": -51,\n \"ip\": \"192.168.2.161\",\n \"type\": \"wifi\",\n \"mac\": \"68:B6:B3:30:3B:94\"\n }\n}"}],"_postman_id":"4668e273-436e-4de6-a408-944a95a541ca"}],"id":"2a0096e0-6a46-4f27-8903-3e112b72ed76","_postman_id":"2a0096e0-6a46-4f27-8903-3e112b72ed76","description":""},{"name":"Control","item":[{"name":"HTTPS Post Command","id":"0424c5e4-e296-4b75-95b6-565f51b7eada","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"x-secret-key","value":"Secret Key","type":"text"}],"body":{"mode":"raw","raw":"{\r\n \"host\": {\r\n \"components\": {\r\n \"0\": {\r\n \"timer\": {\r\n \"duration\": \"30\"\r\n }\r\n }\r\n }\r\n }\r\n}","options":{"raw":{"language":"json"}}},"url":"https://IP_ADDRESS/api/v1/command","urlObject":{"protocol":"https","path":["api","v1","command"],"host":["IP_ADDRESS"],"query":[],"variable":[]}},"response":[{"id":"d7f3a46d-f63d-4883-9837-1e4c9a13c86b","name":"Update Request","originalRequest":{"method":"POST","header":[{"key":"x-secret-key","value":"Secret Key","type":"text"}],"body":{"mode":"raw","raw":"{\r\n \"device\":{\r\n \"update\":true\r\n }\r\n}","options":{"raw":{"language":"json"}}},"url":"https://192.168.0.33/api/v1/command"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"},{"key":"Connection","value":"keep-alive"},{"key":"Content-Length","value":"27"}],"cookie":[],"responseTime":null,"body":"{\n \"device\": {\n \"update\": \"ACK\"\n }\n}"},{"id":"5fb2ec05-32b7-48c8-b9a8-b2b2f023c2d4","name":"Disable Authentication","originalRequest":{"method":"POST","header":[{"key":"x-secret-key","value":"Secret Key","type":"text"}],"body":{"mode":"raw","raw":"{\r\n \"device\":{\r\n \"requireAuth\":false\r\n }\r\n}","options":{"raw":{"language":"json"}}},"url":"https://IP_ADDRESS/api/v1/command"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"},{"key":"Connection","value":"keep-alive"},{"key":"Content-Length","value":"32"}],"cookie":[],"responseTime":null,"body":"{\n \"device\": {\n \"requireAuth\": false\n }\n}"},{"id":"47d9dfd0-0d52-4fca-ab0a-63040a7fa3bd","name":"Set Level to 50","originalRequest":{"method":"POST","header":[{"key":"x-secret-key","value":"Secret Key","type":"text"}],"body":{"mode":"raw","raw":"{\r\n \"host\":{\r\n \"components\":{\r\n \"0\":{\r\n \"level\": {\r\n \"now\": 50\r\n }\r\n }\r\n }\r\n }\r\n}","options":{"raw":{"language":"json"}}},"url":"https://IP_ADDRESS/api/v1/command"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"},{"key":"Connection","value":"keep-alive"},{"key":"Content-Length","value":"42"}],"cookie":[],"responseTime":null,"body":"{\n \"host\": {\n \"components\": {\n \"0\": {\n \"level\": {\n \"now\": 50\n }\n }\n }\n }\n}"},{"id":"d80406d9-b4cb-49e3-afa3-77b921dae6e7","name":"Toggle Off Request","originalRequest":{"method":"POST","header":[{"key":"x-secret-key","value":"Secret Key","type":"text"}],"body":{"mode":"raw","raw":"{\r\n \"host\":{\r\n \"components\":{\r\n \"0\":{\r\n \"toggle\":{\r\n \"state\":\"off\"\r\n }\r\n }\r\n }\r\n }\r\n}","options":{"raw":{"language":"json"}}},"url":"https://IP_ADDRESS/api/v1/command"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Access-Control-Allow-Origin","value":"*"},{"key":"Access-Control-Allow-Headers","value":"x-secret-key"},{"key":"Content-Type","value":"application/json"},{"key":"Connection","value":"keep-alive"},{"key":"Content-Length","value":"56"}],"cookie":[],"responseTime":null,"body":"{\n \"host\": {\n \"components\": {\n \"0\": {\n \"toggle\": {\n \"state\": \"off\"\n }\n }\n }\n }\n}"},{"id":"9a64653c-d364-4dd8-8eeb-7678c24d2abd","name":"Set (New) Static IP","originalRequest":{"method":"POST","header":[{"key":"x-secret-key","type":"text","value":"Secret Key"}],"body":{"mode":"raw","raw":"{\r\n \"device\":{\r\n \"staticIP\":{\r\n \"ip\":\"192.168.0.177\",\r\n \"subnet\":\"255.255.255.0\",\r\n \"gateway\":\"192.168.0.1\",\r\n \"primary\":\"8.8.8.8\",\r\n \"secondary\":\"8.8.4.4\"\r\n }\r\n }\r\n}","options":{"raw":{"language":"json"}}},"url":"https://IP_ADDRESS/api/v1/command"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Access-Control-Allow-Origin","value":"*"},{"key":"Access-Control-Allow-Headers","value":"x-secret-key"},{"key":"Content-Type","value":"application/json"},{"key":"Connection","value":"keep-alive"},{"key":"Content-Length","value":"28"}],"cookie":[],"responseTime":null,"body":"{\n \"device\": {\n \"staticIP\": true\n }\n}"},{"id":"543ab6a7-1c31-48b5-980a-54f280501133","name":"Set USB state","originalRequest":{"method":"POST","header":[{"key":"x-secret-key","type":"text","value":"Secret Key"}],"body":{"mode":"raw","raw":"{\r\n \"insert\": {\r\n \"components\": {\r\n \"usb\": {\r\n \"toggle\": {\r\n \"state\": \"on\"\r\n }\r\n }\r\n }\r\n }\r\n}","options":{"raw":{"language":"json"}}},"url":"https://IP_ADDRESS/api/v1/command"},"_postman_previewlanguage":null,"header":null,"cookie":[],"responseTime":null,"body":null},{"id":"f61571a5-e9d5-4384-bdeb-51f68df0a745","name":"Set Fan Mode","originalRequest":{"method":"POST","header":[{"key":"x-secret-key","value":"Secret Key","type":"text"}],"body":{"mode":"raw","raw":"{\r\n \"host\": {\r\n \"components\": {\r\n \"0\": {\r\n \"mode\": \"heatExchange\"\r\n }\r\n }\r\n }\r\n}","options":{"raw":{"language":"json"}}},"url":"https://IP_ADDRESS/api/v1/command"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"},{"key":"Connection","value":"keep-alive"},{"key":"Content-Length","value":"42"}],"cookie":[],"responseTime":null,"body":"{\n \"host\": {\n \"components\": {\n \"0\": {\n \"mode\": \"heatExchange\"\n }\n }\n }\n}"},{"id":"771d5b17-5ed6-4b4b-b243-bc9bcc466c9b","name":"Set Fan Speed","originalRequest":{"method":"POST","header":[{"key":"x-secret-key","value":"Secret Key","type":"text"}],"body":{"mode":"raw","raw":"{\r\n \"host\": {\r\n \"components\": {\r\n \"0\": {\r\n \"speed\": \"low\"\r\n }\r\n }\r\n }\r\n}","options":{"raw":{"language":"json"}}},"url":"https://IP_ADDRESS/api/v1/command"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"},{"key":"Connection","value":"keep-alive"},{"key":"Content-Length","value":"42"}],"cookie":[],"responseTime":null,"body":"{\n \"host\": {\n \"components\": {\n \"0\": {\n \"speed\": \"low\"\n }\n }\n }\n}"},{"id":"15e7953a-a705-4b2a-87db-e49d54e26e4e","name":"Set Fan Boost","originalRequest":{"method":"POST","header":[{"key":"x-secret-key","value":"Secret Key","type":"text"}],"body":{"mode":"raw","raw":"{\r\n \"host\": {\r\n \"components\": {\r\n \"0\": {\r\n \"boost\": {\r\n \"mode\": \"timer\",\r\n \"minutes\": 5\r\n }\r\n }\r\n }\r\n }\r\n}","options":{"raw":{"language":"json"}}},"url":"https://IP_ADDRESS/api/v1/command"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"},{"key":"Connection","value":"keep-alive"},{"key":"Content-Length","value":"42"}],"cookie":[],"responseTime":null,"body":"{\n \"host\": {\n \"components\": {\n \"0\": {\n \"boost\": {\n \"mode\": \"timer\",\n \"minutes\": 5\n }\n }\n }\n }\n}"}],"_postman_id":"0424c5e4-e296-4b75-95b6-565f51b7eada"},{"name":"HTTPS Update to version","id":"df01d109-e68b-4a39-af56-75989e8e0686","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"x-secret-key","value":"Secret Key","type":"text"}],"body":{"mode":"raw","raw":"{\r\n \"version\":VERSION\r\n}","options":{"raw":{"language":"json"}}},"url":"https://IP_ADDRESS/api/v1/update/version","urlObject":{"protocol":"https","path":["api","v1","update","version"],"host":["IP_ADDRESS"],"query":[],"variable":[]}},"response":[{"id":"cc6019f7-464d-4fc3-8280-96cd26fc1574","name":"Update Request","originalRequest":{"method":"POST","header":[{"key":"x-secret-key","value":"Secret Key","type":"text"}],"body":{"mode":"raw","raw":"{\r\n \"version\":\"1.6.74\"\r\n}","options":{"raw":{"language":"json"}}},"url":"https://192.168.0.33/api/v1/version/update"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"},{"key":"Connection","value":"keep-alive"},{"key":"Content-Length","value":"27"}],"cookie":[],"responseTime":null,"body":"{}"}],"_postman_id":"df01d109-e68b-4a39-af56-75989e8e0686"},{"name":"HTTPS Factory Reset","id":"1021e8f2-e27f-45f2-8c15-f806ba955a3d","protocolProfileBehavior":{"disableBodyPruning":true,"disabledSystemHeaders":{"connection":true}},"request":{"method":"DELETE","header":[{"key":"x-secret-key","type":"text","value":"Secret Key"}],"url":"https://IP_ADDRESS/api/v1/reset","urlObject":{"protocol":"https","path":["api","v1","reset"],"host":["IP_ADDRESS"],"query":[],"variable":[]}},"response":[{"id":"886ba087-1533-49af-b645-376ac30414a5","name":"Factory Reset","originalRequest":{"method":"DELETE","header":[{"key":"x-secret-key","type":"text","value":"Secret Key"}],"url":"https://IP_ADDRESS/api/v1/reset"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"reset\": true\n}"}],"_postman_id":"1021e8f2-e27f-45f2-8c15-f806ba955a3d"},{"name":"HTTPS blink","id":"993e0d8d-8104-4f18-b51d-5791bd248af7","protocolProfileBehavior":{"disableBodyPruning":true,"disabledSystemHeaders":{"connection":true}},"request":{"method":"GET","header":[],"url":"https://IP_ADDRESS/blink?x-user-key=dqMMBX9deuwtkkp784ewTjqo76IYfThV","urlObject":{"protocol":"https","path":["blink"],"host":["IP_ADDRESS"],"query":[{"key":"x-user-key","value":"dqMMBX9deuwtkkp784ewTjqo76IYfThV"}],"variable":[]}},"response":[],"_postman_id":"993e0d8d-8104-4f18-b51d-5791bd248af7"},{"name":"HTTPS ping","id":"183dd64e-04dc-492c-9186-149163cf8e90","protocolProfileBehavior":{"disableBodyPruning":true,"disabledSystemHeaders":{"connection":true}},"request":{"method":"GET","header":[],"url":"https://IP_ADDRESS/ping?x-secret-key=Secret Key","urlObject":{"protocol":"https","path":["ping"],"host":["IP_ADDRESS"],"query":[{"key":"x-secret-key","value":"Secret Key"}],"variable":[]}},"response":[],"_postman_id":"183dd64e-04dc-492c-9186-149163cf8e90"}],"id":"091dace2-47d7-4335-a104-720db3ed8e90","_postman_id":"091dace2-47d7-4335-a104-720db3ed8e90","description":""},{"name":"Configuration","item":[{"name":"HTTPS Get Config","id":"42d5f1d7-5357-487b-8801-74f44f13914d","protocolProfileBehavior":{"disableBodyPruning":true,"disabledSystemHeaders":{"connection":true}},"request":{"method":"GET","header":[{"key":"x-secret-key","value":"Secret Key","type":"text"},{"key":"Connection","value":"close","type":"text"}],"url":"https://IP_ADDRESS/api/v1/device_config","urlObject":{"protocol":"https","path":["api","v1","device_config"],"host":["IP_ADDRESS"],"query":[],"variable":[]}},"response":[{"id":"7524eb71-c2e2-4724-80c8-c101c0fa9272","name":"Get Config - Fan (IB160)","originalRequest":{"method":"GET","header":[{"key":"x-secret-key","value":"Secret Key","type":"text"},{"key":"x-user-key","value":"User Key","type":"text","disabled":true},{"key":"Connection","value":"close","type":"text"}],"url":"https://IP_ADDRESS/api/v1/device_config"},"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"{\n \"device\": {\n \"proactiveReporting\": false,\n \"uploadBatchTime\": 21600\n },\n \"updater\": {\n \"autoUpdate\": false\n },\n \"insert\": {\n \"components\": {}\n },\n \"host\": {\n \"components\": {\n \"0\": {\n \"singlePole\": false,\n \"spInvert\": false,\n \"log_rate\": 300000,\n \"toggle\": {\n \"lock\": \"unlocked\"\n },\n \"model\": 6,\n \"defaultTimer\": 0,\n \"lowSa\": 60,\n \"lowEa\": 60,\n \"highSa\": 100,\n \"highEa\": 100,\n \"boostSa\": 110,\n \"boostEa\": 110,\n \"balancing\": 1\n }\n }\n },\n \"reporter\": {\n \"stateUpdates\": false\n },\n \"led\": {\n \"lightSuppress\": false,\n \"brightness\": 100,\n \"lightInverse\": false\n },\n \"op\": {\n \"logging\": false,\n \"button_factory_reset\": true\n },\n \"tz\": {\n \"posix\": \"\"\n },\n \"loc\": {\n \"lat\": 0,\n \"lng\": 0\n },\n \"access\": {\n \"site_key\": \"none\",\n \"user_key\": \"none\"\n },\n \"configServer\": {\n \"debugEnabled\": true\n },\n \"l_ctrl\": {\n \"name\": \"Swidget Device\"\n }\n}"}],"_postman_id":"42d5f1d7-5357-487b-8801-74f44f13914d"},{"name":"HTTPS Post Config","id":"4fcb4582-3e13-46e7-ab18-2f1aa11b43f9","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"x-secret-key","type":"text","value":"Secret Key"}],"body":{"mode":"raw","raw":"{}","options":{"raw":{"language":"json"}}},"url":"https://IP_ADDRESS/api/v1/device_config","urlObject":{"protocol":"https","path":["api","v1","device_config"],"host":["IP_ADDRESS"],"query":[],"variable":[]}},"response":[{"id":"0f5cbc11-a791-4c7e-ac55-d924d7e1211a","name":"Set Device Name","originalRequest":{"method":"POST","header":[{"key":"x-secret-key","value":"Secret Key","type":"text"},{"key":"x-user-key","value":"User Key","type":"text","disabled":true}],"body":{"mode":"raw","raw":"{\r\n \"l_ctrl\": {\r\n \"name\": \"New Name\"\r\n }\r\n}","options":{"raw":{"language":"json"}}},"url":"https://IP_ADDRESS/api/v1/device_config"},"_postman_previewlanguage":"","header":[],"cookie":[{"expires":"Invalid Date","domain":"","path":""}],"responseTime":null,"body":""}],"_postman_id":"4fcb4582-3e13-46e7-ab18-2f1aa11b43f9"}],"id":"1308303b-c974-4b67-8daa-b294bff70ac8","description":"

Each Swidget Device has a variety of configuration parameters that can modify the behaviour of the device. These parameters can be read and set using the same access patterns.

updater\n    autoUpdate: BOOL - enable / disable auto updates (All Devices)\n\nled\n    lightSupress: BOOL - enable / disable indicating host state (All Devices)\n    brightness: INT - 0 to 100, set brightness (All Devices)\n    lightInverse: BOOL - invert host state indication (All Devices)\n\ntz\n    posix: STRING - Timezone in posix format (All Devices)\n\nloc\n    lat: FLOAT - Latitude of location (All Devices)\n    lng: FLOAT - Longitude of location (All Devices)\n\nl_ctrl\n    name: STRING - Device Name (All Devices)\n\nhost\n    components\n        {ID} - component ID\n            singlePole: BOOL - single vs multiway switch configuration (3-Way Switches)\n            spInvert: BOOL - invert on/off switch control (3-Way Switches)\n            toggle\n                lock: \"unlocked\" | \"lock_on\" | \"lock_off\" - Lock Host Control (Switch's and Outlet's controllable component)\n            minBrightness: INT - set minimum brightness (Dimmers)\n            maxBrightness: INT - set minimum brightness (Dimmers)\n            timer - (TFS Switches)\n                lv1: INT - Duration in minutes of first level of timer\n                lv2: INT - Duration in minutes of second level of timer\n                lv3: INT - Duration in minutes of third level of timer\n            defaultTimer: INT - Fan Default Timer (Fans)\n            defaultEa: INT - Default Exhaust Air Fan Speed (Fans)\n            defaultSa: INT - Default Supply Air Fan Speed (Fans)\n            highEa: INT - Boost Exhaust Air Fan Speed (Fans with Exhaust Boost)\n            highSa: INT - Boost Supply Air Fan Speed (Fans with Supply Boost)\n            balancing: BOOL - Balancing Enabled (Fans)\n            \n

","_postman_id":"1308303b-c974-4b67-8daa-b294bff70ac8"}],"id":"4e524ec6-0960-480d-af0d-19171dcc1309","description":"

Summary

The Device API is consists of an HTTPS server that processes device requests.

By default, the API is authenticated via the secret key that was returned during provisioning. Authentication can be toggled on or off.

When Authentication is disabled, TLS connections are not required. E.g. http:// as opposed to https:// is possible. This also applies to the WebSocket connections.

The structure of a device is as follows:

Each device is composed of a host and an insert
\n
Both the host and the insert provide a list of components
\n
Each component within the device is given a locally unique ID, host component id's are incrementing numbers, whereas insert component id's are pre-specified.
\n
Each component provides a list of functions.
\n
Each Function can accept a command object, and each will return a data object.
\n

All data fields for a function will be returned with each state request.
Each field of the command object is optional when issuing a command.

Usage

The Get Summary request should be the first request called, as it is used to gather information about what capabilities exist within the device. This request should be used to create a logical map of the device on the client.

Periodic Get State requests should be used to retreive the current state of the device. These requests should not occur more frequent than 2 times a second. Alternatively, a WebSocket connection (described below) can be used to remove the neccessity of querying for the device state periodically.

The Post Request is used to make changes to the device. This request object can contain commands for multiple functions in the same request. This will respond with the new state of the updated field. These requests can also be made through the WebSocket once that connection is established.

It is recommended to have a maximum of 2 active HTTPS connections to the device, including Websocket Connection.

Generic Host Functions

power

Power consumption information for the component, measured in watts.

data

{\n    current: FLOAT,\n    avg: FLOAT,\n    avgOn: FLOAT\n}\n\n

toggle

The ability to toggle power on the component on and off.

data

{\n    state: \"ON\" | \"OFF\"\n}\n

command

{\n    state: \"ON\" | \"OFF\"\n}\n\n

Dimmer Functions

level

The ability to set the power level as a percentage, e.g. for dimmable lights.

data

{\n    now: INT\n}\n\n

command

{\n    now: INT [0..100]\n}\n\n

Timer Switch Functions

timer

The ability to turn the component on for a set duration.

data

{\n    buttonTimer: INT\n    buttonLevel: INT\n    autoTimer: INT\n    autoLevel: INT\n}\n\n

buttonTimer returns the number of minutes remaining before the switch turns off.
\n
buttonLevel returns the LED state of the switch.
\n
autoTimer and autoLevel refer to currently unused for this application.
\n

command

{\n    duration: INT\n}\n\n

Fan Functions

dutyCycle

Duty Cycle for the component, in minutes.

data

{\n    minutes: INT,\n}\n

minutes returns the current duty cycle in minutes

command

{\n    minutes: INT,\n}\n

minutes sets the duty cycle

exhaust

Exhaust Fan info

data

{\n    cfm: INT\n}\n

cfm returns the exhaust air flow in cfm

supply

Supply Fan info

data

{\n    cfm: INT\n}\n

cfm returns the supply air flow in cfm

status

Fan Status

data

\"normal\" | \"defrost\" | \"boost\" | \"humidity\" | \"auto\" | \"int\" | \"limit\" | \"balancing\" | \"unknown\"\n

returns current fan status

mode

Fan Mode

data

\"heatExchange\" | \"supply\" | \"exhaust\" | \"recirculation\"\n

returns current fan mode

command

\"heatExchange\" | \"supply\" | \"exhaust\" | \"recirculation\"\n

set the fan mode

speed

Fan Speed

data

\"low\" | \"high\"\n

returns current fan speed

command

\"low\" | \"high\"\n

set the fan speed

boost

Fan Boost Mode

data

{\n    mode: \"off\" | \"timer\" | \"on\"\n    minutes: INT\n}\n

mode returns the current boost mode
minutes returns the remaining duration for the mode

command

{\n    mode: \"off\" | \"timer\" | \"on\"\n    minutes: INT\n}\n

mode sets the boost mode
minutes sets the duration for the mode

indoors

Fan indoor climate info

data

{\n    temperature: FLOAT,\n    humidity: FLOAT\n}\n

temperature returns fan's temperature reading (not available on all models)
humidity returns fan's humidity reading (not available on all models)

outdoors

Fan outdoor climate info

data

{\n    temperature: FLOAT,\n    humidity: FLOAT\n}\n

temperature returns fan's temperature reading (not available on all models)
humidity returns fan's humidity reading (not available on all models)

filter

Fan filter info

data

{\n    needsReplacement: BOOL,\n    needsCleaning: BOOL\n}\n

needsReplacement returns if the fan filter needs to be replaced
needsCleaning returns if the fans filter needs cleaning

command

{\n    clean: BOOL\n}\n

clean will inform the fan that the filter is clean when set to true

light

Fan light

data

{\n    on: BOOL\n}\n

on returns if the fan light is on

command

{\n    on: BOOL\n}\n

on turns the fan light on or off

modules

Fan modules

data

{\n    condensation: \"triggered\" : \"dormant\",\n    motion: \"triggered\" : \"dormant\"\n}\n

condensation returns the condensation module status (only available when condensation module is in use)
motion returns the motion module status (only available when motion module is in use)

Insert Functions

temperature

Temperature information for the component, measured in temperature.

data

{  \nnow: FLOAT  \n}\n\n

command

{  \nrecalibrate: BOOL | INT  \n}\n\n

humidity

Humidity information for the component, measured in relative humidity.

data

{  \nnow: FLOAT  \n}\n\n

tvoc

Total Volatile Organic Compounds Information for the component.

data

{  \nnow: FLOAT  \n}\n\n

eco2

Estimated CO2 Information for the component.

data

{  \nnow: FLOAT  \n}\n\n

iaq

Air Quality Information for the component.

data

{  \nnow: FLOAT  \ngrade: INT  \n}\n\n

Grade: A value from 1-7 representing air quality. 1 = Best, 7 = Worst
\n
occupied
\n

Occupancy information for the componant.\n#### data\n\n

{  \nstate: BOOL,  \nsecondsInState: INT  \n}\n\n

","event":[{"listen":"prerequest","script":{"id":"3be2fed5-0e19-47ff-aa5f-d980ca949f14","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"92828eee-d175-4352-8da4-60a237f7b6f9","type":"text/javascript","exec":[""]}}],"_postman_id":"4e524ec6-0960-480d-af0d-19171dcc1309"},{"name":"Websocket","item":[],"id":"6a0b7aeb-b137-4373-9450-b4647a8b528a","description":"

Websocket API

The device can accept a Websocket (wss: / ws:) connection at the endpoint.
Each device is capable of maintaining one Websocket connection at a time.
When authentication is enabled on the device, this request must provide the secret key, either as a header or as a query parameter, e.g.:

wss://<IP>/api/v1/sock?x-secret-key=MYSECRETTOKEN\n

The Websocket can be used to make requests to the insert, as well as poll for the state and summary information.\nThese requests must specify a type, and an ID. The ID will be included in the response JSON as a means to map requests to responses.

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Request Type	Corresponds to
summary	GET api/v1/summary
state	GET api/v1/state
command	POST api/v1/command

Example Summary Request:

{\n    \"type\":\"summary\",\n    \"request_id\":\"abcd\"\n}\n\nResponse:\n\n{\n    \"request_id\":\"abcd\",\n    \"model\":\"HK_PICO_1\",\n    \"mac\":\"24a16074d77c\",\n    \"version\":\"1.3.27\",\n    \"host\":{\n        \"id\":\"303DFFA720g\",\n        \"type\":\"dimmer\",\n        \"error\":0,\n        \"components\":[\n            {\"id\":\"0\",\"functions\":[\"power\",\"level\",\"toggle\"]}\n        ]\n    },\n    \"insert\":{\n        \"type\":\"TEMP HUMI\",\n        \"components\":[\n            {\"id\":\"temp\",\"functions\":[\"temperature\"]},\n            {\"id\":\"humi\",\"functions\":[\"humidity\"]}\n        ]\n    }\n}\n

Example State Request:

{\n    \"type\":\"state\",\n    \"request_id\":\"abcd\n}\n\nResponse:\n{\n    \"request_id\":\"abcd\",\n    \"insert\":{\n        \"components\":{\n            \"temp\":{\"temperature\":{\"now\":26.35}},\n            \"humi\":{\"humidity\":{\"now\":10.77}}\n        }\n    },\n    \"host\":{\n        \"components\":{\n            \"0\":{\"toggle\":{\"state\":\"on\"},\"level\":{\"now\":1},\"power\":{\"current\":0,\"avg\":0,\"avgOn\":0}}\n        }\n    },\n    ...\n}\n

A command request must also include a payload containing the command to be executed:

{\n    \"type\":\"command\",\n    \"request_id\":\"1234-5678-9012\",\n    \"payload\":{\n        \"host\":{\n            \"components\":{\n                \"0\":{\n                    \"toggle\":{\n                        \"state\":\"on\"\n                    }\n                }\n            }\n        }\n    }\n}\n

The device will also output it's state dynamically when any change occurs:

{\n    \"request_id\":\"DYNAMIC_UPDATE\",\n    \"insert\":{\n        \"components\":{\n            \"temp\":{\"temperature\":{\"now\":26.35}},\n            \"humi\":{\"humidity\":{\"now\":10.77}}\n        }\n    },\n    \"host\":{\n        \"components\":{\n            \"0\":{\"toggle\":{\"state\":\"on\"},\"level\":{\"now\":1},\"power\":{\"current\":0,\"avg\":0,\"avgOn\":0}}\n        }\n    },\n    ...\n}\n

","event":[{"listen":"prerequest","script":{"id":"477e8588-fe33-46ff-a108-38f5e9e91822","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"646b432f-3851-46c3-bbdb-944a6d17cdaa","type":"text/javascript","exec":[""]}}],"_postman_id":"6a0b7aeb-b137-4373-9450-b4647a8b528a"}],"event":[{"listen":"prerequest","script":{"id":"54feea7a-e32f-4f52-9cd8-b68bd90c4635","type":"text/javascript","requests":{},"exec":[""]}},{"listen":"test","script":{"id":"0a7d7ac0-d756-42d4-9732-3cfacc025829","type":"text/javascript","requests":{},"exec":[""]}}],"variable":[{"key":"DeviceIp","value":"IP_ADDRESS"},{"key":"Auth Key","value":"Secret Key"},{"key":"Network Password","value":"PSK"},{"key":"Network SSID","value":"SSID"},{"key":"User Key","value":"User Key"}]}