|
| 1 | +# APIv3: Socket.IO alarm channel |
| 2 | + |
| 3 | +### Complete sample client code |
| 4 | +```html |
| 5 | +<!DOCTYPE html> |
| 6 | +<html lang="en"> |
| 7 | + <head> |
| 8 | + <meta charset="utf-8" /> |
| 9 | + <meta http-equiv="x-ua-compatible" content="ie=edge" /> |
| 10 | + <meta name="viewport" content="width=device-width, initial-scale=1" /> |
| 11 | + |
| 12 | + <title>APIv3 Socket.IO sample for alarms</title> |
| 13 | + |
| 14 | + <link rel="icon" href="images/favicon.png" /> |
| 15 | + </head> |
| 16 | + |
| 17 | + <body> |
| 18 | + <script src="https://cdnjs.cloudflare.com/ajax/libs/socket.io/2.2.0/socket.io.js"></script> |
| 19 | + |
| 20 | + <script> |
| 21 | + const socket = io('https://nsapiv3.herokuapp.com/alarm'); |
| 22 | +
|
| 23 | + socket.on('connect', function () { |
| 24 | + socket.emit('subscribe', { |
| 25 | + accessToken: 'testadmin-ad3b1f9d7b3f59d5' |
| 26 | + }, function (data) { |
| 27 | + if (data.success) { |
| 28 | + console.log('subscribed for alarms', data.message); |
| 29 | + } |
| 30 | + else { |
| 31 | + console.error(data.message); |
| 32 | + } |
| 33 | + }); |
| 34 | + }); |
| 35 | +
|
| 36 | + socket.on('announcement', function (data) { |
| 37 | + console.log(`${data.colName}:created document`, data.doc); |
| 38 | + }); |
| 39 | +
|
| 40 | + socket.on('alarm', function (data) { |
| 41 | + console.log(`${data.colName}:updated document`, data.doc); |
| 42 | + }); |
| 43 | +
|
| 44 | + socket.on('urgent_alarm', function (data) { |
| 45 | + console.log(`${data.colName}:deleted document with identifier`, data.identifier); |
| 46 | + }); |
| 47 | +
|
| 48 | + socket.on('clear_alarm', function (data) { |
| 49 | + console.log(`${data.colName}:deleted document with identifier`, data.identifier); |
| 50 | + }); |
| 51 | + </script> |
| 52 | + </body> |
| 53 | +</html> |
| 54 | +``` |
| 55 | + |
| 56 | +### Subscription (authorization) |
| 57 | +The client must first subscribe to the channel that is exposed at `alarm` namespace, ie the `/alarm` subadress of the base Nightscout's web address (without `/api/v3` subaddress). |
| 58 | +```javascript |
| 59 | +const socket = io('https://nsapiv3.herokuapp.com/alarm'); |
| 60 | +``` |
| 61 | + |
| 62 | + |
| 63 | +Subscription is requested by emitting `subscribe` event to the server, while including document with parameter: |
| 64 | +* `accessToken`: required valid accessToken of the security subject, which has been prepared in *Admin Tools* of Nightscout. |
| 65 | + |
| 66 | +```javascript |
| 67 | +socket.on('connect', function () { |
| 68 | + socket.emit('subscribe', { |
| 69 | + accessToken: 'testadmin-ad3b1f9d7b3f59d5' |
| 70 | + }, ... |
| 71 | +``` |
| 72 | +
|
| 73 | +
|
| 74 | +On the server, the subject is identified and authenticated (by the accessToken). Ne special rights are required. |
| 75 | +
|
| 76 | +If the authentication was successful `success` = `true` is set in the response object and the field `message` contains a text response. |
| 77 | +In other case `success` = `false` is set in the response object and the field `message` contains an error message. |
| 78 | +
|
| 79 | +```javascript |
| 80 | +function (data) { |
| 81 | + if (data.success) { |
| 82 | + console.log('subscribed for alarms', data.message); |
| 83 | + } |
| 84 | + else { |
| 85 | + console.error(data.message); |
| 86 | + } |
| 87 | + }); |
| 88 | +}); |
| 89 | +``` |
| 90 | + |
| 91 | +### Acking alarms and announcements |
| 92 | +If the client is successfully subscribed it can ack alarms and announcements by emitting `ack` message. |
| 93 | + |
| 94 | +```javascript |
| 95 | + socket.emit('ack', level, group, silenceTimeInMilliseconds); |
| 96 | +``` |
| 97 | + |
| 98 | +where `level` and `group` are values from alarm being acked and `silenceTimeInMilliseconds` is duration. During this time alarms of the same type are not emmited. |
| 99 | + |
| 100 | +### Receiving events |
| 101 | +After the successful subscription the client can start listening to `announcement`, `alarm` , `urgent_alarm` and/or `clear_alarm` events of the socket. |
| 102 | + |
| 103 | + |
| 104 | +##### announcement |
| 105 | + |
| 106 | +The received object contains similiar json: |
| 107 | + |
| 108 | +```javascript |
| 109 | + { |
| 110 | + "level":0, |
| 111 | + "title":"Announcement", |
| 112 | + "message":"test", |
| 113 | + "plugin":{"name":"treatmentnotify","label":"Treatment Notifications","pluginType":"notification","enabled":true}, |
| 114 | + "group":"Announcement", |
| 115 | + "isAnnouncement":true, |
| 116 | + "key":"9ac46ad9a1dcda79dd87dae418fce0e7955c68da" |
| 117 | + } |
| 118 | +``` |
| 119 | + |
| 120 | + |
| 121 | +##### alarm, urgent_alarm |
| 122 | + |
| 123 | +The received object contains similiar json: |
| 124 | + |
| 125 | +```javascript |
| 126 | + { |
| 127 | + "level":1, |
| 128 | + "title":"Warning HIGH", |
| 129 | + "message":"BG Now: 5 -0.2 → mmol\/L\nRaw BG: 4.8 mmol\/L Čistý\nBG 15m: 4.8 mmol\/L\nIOB: -0.02U\nCOB: 0g", |
| 130 | + "eventName":"high", |
| 131 | + "plugin":{"name":"simplealarms","label":"Simple Alarms","pluginType":"notification","enabled":true}, |
| 132 | + "pushoverSound":"climb", |
| 133 | + "debug":{"lastSGV":5,"thresholds":{"bgHigh":180,"bgTargetTop":75,"bgTargetBottom":72,"bgLow":70}}, |
| 134 | + "group":"default", |
| 135 | + "key":"simplealarms_1" |
| 136 | + } |
| 137 | +``` |
| 138 | + |
| 139 | + |
| 140 | +##### clear_alarm |
| 141 | + |
| 142 | +The received object contains similiar json: |
| 143 | + |
| 144 | +```javascript |
| 145 | + { |
| 146 | + "clear":true, |
| 147 | + "title":"All Clear", |
| 148 | + "message":"default - Urgent was ack'd", |
| 149 | + "group":"default" |
| 150 | + } |
| 151 | +``` |
0 commit comments