Adding warning regarding imports and updated to the latest beta for improved usage of const enums

accessory-example-typescript/package-lock.json

@@ -237,9 +237,9 @@
       }
     },
     "hap-nodejs": {
-      "version": "0.6.2",
+      "version": "0.6.3",
-      "resolved": "https://registry.npmjs.org/hap-nodejs/-/hap-nodejs-0.6.2.tgz",
+      "resolved": "https://registry.npmjs.org/hap-nodejs/-/hap-nodejs-0.6.3.tgz",
-      "integrity": "sha512-/LlRaYCtcwC4jBUKRJeBUdUfKEp8w/NK3PNYXaAOngQL9uVnqsvQ0Gce/mUhSXPhsxfdnxbHVT870W9OEnV6+A==",
+      "integrity": "sha512-FH5cEBJDz1e/IzqYbGEO4PdydXrZN+vqZcvKexyRqZlP1DbPjjeboI2TbqGfftUsyZu2jz5y/NRYlS9HzEijcQ==",
       "dev": true,
       "requires": {
         "bonjour-hap": "3.5.4",
@@ -273,14 +273,14 @@
       "dev": true
     },
     "homebridge": {
-      "version": "0.4.54-beta.51",
+      "version": "0.4.54-beta.52",
-      "resolved": "https://registry.npmjs.org/homebridge/-/homebridge-0.4.54-beta.51.tgz",
+      "resolved": "https://registry.npmjs.org/homebridge/-/homebridge-0.4.54-beta.52.tgz",
-      "integrity": "sha512-WycAihWBzWu+8ZBnVrU4wqdU0bq/cT43iKdk2+6ODhbGh/xlaxIFpMdSGX++YqwGpu7cNEL0L45Woj9sEfFYNw==",
+      "integrity": "sha512-fQKpd2khare7BTbzyEVjABWLhAeTUF1it5MrvnI/NDlzkvehPv362j8Jim1/sVyafbY+RloC0z5vFdu1nkNvoA==",
       "dev": true,
       "requires": {
         "chalk": "^3.0.0",
         "commander": "5.0.0",
-        "hap-nodejs": "0.6.2",
+        "hap-nodejs": "0.6.3",
         "node-persist": "^0.0.11",
         "qrcode-terminal": "^0.12.0",
         "semver": "^7.1.3",

accessory-example-typescript/package.json

@@ -33,6 +33,6 @@
     "@types/node": "10.17.19",
     "typescript": "^3.8.3",
     "rimraf": "^3.0.2",
-    "homebridge": "^0.4.54-beta.51"
+    "homebridge": "^0.4.54-beta.52"
   }
 }

accessory-example-typescript/src/accessory.ts

@@ -2,6 +2,7 @@ import {
   AccessoryConfig,
   AccessoryPlugin,
   API,
+  CharacteristicEventTypes,
   CharacteristicGetCallback,
   CharacteristicSetCallback,
   CharacteristicValue,
@@ -10,8 +11,27 @@ import {
   Service
 } from "homebridge";
 
-/**
+/*
- * TODO explain
+ * IMPORTANT NOTICE
+ *
+ * One thing you need to take care of is, that you never ever ever import anything directly from the "homebridge" module (or the "hap-nodejs" module).
+ * The above import block may seem like, that we do exactly that, but actually those imports are only used for types and interfaces
+ * and will disappear once the code is compiled to Javascript.
+ * In fact you can check that by running `npm run build` and opening the compiled Javascript file in the `dist` folder.
+ * You will notice that the file does not contain a `... = require("homebridge");` statement anywhere in the code.
+ *
+ * The contents of the above import statement MUST ONLY be used for type annotation or accessing things like CONST ENUMS,
+ * which is a special case as they get replaced by the actual value and do not remain as a reference in the compiled code.
+ * Meaning normal enums are bad, const enums can be used.
+ *
+ * You MUST NOT import anything else which remains as a reference in the code, as this will result in
+ * a `... = require("homebridge");` to be compiled into the final Javascript code.
+ * This typically leads to unexpected behavior at runtime, as in many cases it won't be able to find the module
+ * or will import another instance of homebridge causing collisions.
+ *
+ * To mitigate this the {@link API | Homebridge API} exposes the whole suite of HAP-NodeJS inside the `hap` property
+ * of the api object, which can be acquired for example in the initializer function. This reference can be stored
+ * like this for example and used to access all exported variables and classes from HAP-NodeJS.
  */
 let hap: HAP;
 
@@ -38,11 +58,11 @@ class ExampleSwitch implements AccessoryPlugin {
 
     this.switchService = new hap.Service.Switch(this.name);
     this.switchService.getCharacteristic(hap.Characteristic.On)
-      .on(hap.CharacteristicEventTypes.GET, (callback: CharacteristicGetCallback) => {
+      .on(CharacteristicEventTypes.GET, (callback: CharacteristicGetCallback) => {
         log.info("Current state of the switch was returned: " + (this.switchOn? "ON": "OFF"));
         callback(undefined, this.switchOn);
       })
-      .on(hap.CharacteristicEventTypes.SET, (value: CharacteristicValue, callback: CharacteristicSetCallback) => {
+      .on(CharacteristicEventTypes.SET, (value: CharacteristicValue, callback: CharacteristicSetCallback) => {
         this.switchOn = value as boolean;
         log.info("Switch state was set to: " + (this.switchOn? "ON": "OFF"));
         callback();

bridged-camera-example-typescript/package-lock.json

@@ -246,9 +246,9 @@
       }
     },
     "hap-nodejs": {
-      "version": "0.6.2",
+      "version": "0.6.3",
-      "resolved": "https://registry.npmjs.org/hap-nodejs/-/hap-nodejs-0.6.2.tgz",
+      "resolved": "https://registry.npmjs.org/hap-nodejs/-/hap-nodejs-0.6.3.tgz",
-      "integrity": "sha512-/LlRaYCtcwC4jBUKRJeBUdUfKEp8w/NK3PNYXaAOngQL9uVnqsvQ0Gce/mUhSXPhsxfdnxbHVT870W9OEnV6+A==",
+      "integrity": "sha512-FH5cEBJDz1e/IzqYbGEO4PdydXrZN+vqZcvKexyRqZlP1DbPjjeboI2TbqGfftUsyZu2jz5y/NRYlS9HzEijcQ==",
       "dev": true,
       "requires": {
         "bonjour-hap": "3.5.4",
@@ -282,14 +282,14 @@
       "dev": true
     },
     "homebridge": {
-      "version": "0.4.54-beta.51",
+      "version": "0.4.54-beta.52",
-      "resolved": "https://registry.npmjs.org/homebridge/-/homebridge-0.4.54-beta.51.tgz",
+      "resolved": "https://registry.npmjs.org/homebridge/-/homebridge-0.4.54-beta.52.tgz",
-      "integrity": "sha512-WycAihWBzWu+8ZBnVrU4wqdU0bq/cT43iKdk2+6ODhbGh/xlaxIFpMdSGX++YqwGpu7cNEL0L45Woj9sEfFYNw==",
+      "integrity": "sha512-fQKpd2khare7BTbzyEVjABWLhAeTUF1it5MrvnI/NDlzkvehPv362j8Jim1/sVyafbY+RloC0z5vFdu1nkNvoA==",
       "dev": true,
       "requires": {
         "chalk": "^3.0.0",
         "commander": "5.0.0",
-        "hap-nodejs": "0.6.2",
+        "hap-nodejs": "0.6.3",
         "node-persist": "^0.0.11",
         "qrcode-terminal": "^0.12.0",
         "semver": "^7.1.3",

bridged-camera-example-typescript/package.json

@@ -37,6 +37,6 @@
     "@types/ip": "^1.1.0",
     "typescript": "^3.8.3",
     "rimraf": "^3.0.2",
-    "homebridge": "^0.4.54-beta.51"
+    "homebridge": "^0.4.54-beta.52"
   }
 }

bridged-camera-example-typescript/src/dynamic-camera-platform.ts

@@ -15,8 +15,27 @@ import {ExampleFFMPEGStreamingDelegate} from "./streamingDelegate";
 const PLUGIN_NAME = "homebridge-bridged-camera-example";
 const PLATFORM_NAME = "ExampleDynamicCameraPlatform";
 
-/**
+/*
- * TODO explain
+ * IMPORTANT NOTICE
+ *
+ * One thing you need to take care of is, that you never ever ever import anything directly from the "homebridge" module (or the "hap-nodejs" module).
+ * The above import block may seem like, that we do exactly that, but actually those imports are only used for types and interfaces
+ * and will disappear once the code is compiled to Javascript.
+ * In fact you can check that by running `npm run build` and opening the compiled Javascript file in the `dist` folder.
+ * You will notice that the file does not contain a `... = require("homebridge");` statement anywhere in the code.
+ *
+ * The contents of the above import statement MUST ONLY be used for type annotation or accessing things like CONST ENUMS,
+ * which is a special case as they get replaced by the actual value and do not remain as a reference in the compiled code.
+ * Meaning normal enums are bad, const enums can be used.
+ *
+ * You MUST NOT import anything else which remains as a reference in the code, as this will result in
+ * a `... = require("homebridge");` to be compiled into the final Javascript code.
+ * This typically leads to unexpected behavior at runtime, as in many cases it won't be able to find the module
+ * or will import another instance of homebridge causing collisions.
+ *
+ * To mitigate this the {@link API | Homebridge API} exposes the whole suite of HAP-NodeJS inside the `hap` property
+ * of the api object, which can be acquired for example in the initializer function. This reference can be stored
+ * like this for example and used to access all exported variables and classes from HAP-NodeJS.
  */
 let hap: HAP;
 let Accessory: typeof PlatformAccessory;

bridged-camera-example-typescript/src/streamingDelegate.ts

@@ -2,7 +2,8 @@ import ip from "ip";
 import {ChildProcess, spawn} from "child_process";
 import {
   CameraController,
-  CameraStreamingDelegate, HAP,
+  CameraStreamingDelegate,
+  HAP,
   PrepareStreamCallback,
   PrepareStreamRequest,
   PrepareStreamResponse,
@@ -130,7 +131,7 @@ export class ExampleFFMPEGStreamingDelegate implements CameraStreamingDelegate {
     const sessionId = request.sessionID;
 
     switch (request.type) {
-      case this.hap.StreamRequestTypes.START:
+      case StreamRequestTypes.START:
         const sessionInfo = this.pendingSessions[sessionId];
 
         const video: VideoInfo = request.video;
@@ -158,8 +159,8 @@ export class ExampleFFMPEGStreamingDelegate implements CameraStreamingDelegate {
           `-c:v libx264 -pix_fmt yuv420p -r ${fps} -an -sn -dn -b:v ${maxBitrate}k -bufsize ${2*maxBitrate}k -maxrate ${maxBitrate}k ` +
           `-payload_type ${payloadType} -ssrc ${ssrc} -f rtp `; // -profile:v ${profile} -level:v ${level}
 
-        if (cryptoSuite !== this.hap.SRTPCryptoSuites.NONE) { // actually ffmpeg just supports AES_CM_128_HMAC_SHA1_80
+        if (cryptoSuite === SRTPCryptoSuites.AES_CM_128_HMAC_SHA1_80) { // actually ffmpeg just supports AES_CM_128_HMAC_SHA1_80
-          videoffmpegCommand += `-srtp_out_suite ${this.hap.SRTPCryptoSuites[cryptoSuite]} -srtp_out_params ${videoSRTP} s`;
+          videoffmpegCommand += `-srtp_out_suite AES_CM_128_HMAC_SHA1_80 -srtp_out_params ${videoSRTP} s`;
         }
 
         videoffmpegCommand += `rtp://${address}:${videoPort}?rtcpport=${videoPort}&localrtcpport=${videoPort}&pkt_size=${mtu}`;
@@ -207,12 +208,12 @@ export class ExampleFFMPEGStreamingDelegate implements CameraStreamingDelegate {
         delete this.pendingSessions[sessionId];
 
         break;
-      case this.hap.StreamRequestTypes.RECONFIGURE:
+      case StreamRequestTypes.RECONFIGURE:
         // not supported by this example
         console.log("Received (unsupported) request to reconfigure to: " + JSON.stringify(request.video));
         callback();
         break;
-      case this.hap.StreamRequestTypes.STOP:
+      case StreamRequestTypes.STOP:
         const ffmpegProcess = this.ongoingSessions[sessionId];
 
         try {

dynamic-platform-example-typescript/package-lock.json

@@ -237,9 +237,9 @@
       }
     },
     "hap-nodejs": {
-      "version": "0.6.2",
+      "version": "0.6.3",
-      "resolved": "https://registry.npmjs.org/hap-nodejs/-/hap-nodejs-0.6.2.tgz",
+      "resolved": "https://registry.npmjs.org/hap-nodejs/-/hap-nodejs-0.6.3.tgz",
-      "integrity": "sha512-/LlRaYCtcwC4jBUKRJeBUdUfKEp8w/NK3PNYXaAOngQL9uVnqsvQ0Gce/mUhSXPhsxfdnxbHVT870W9OEnV6+A==",
+      "integrity": "sha512-FH5cEBJDz1e/IzqYbGEO4PdydXrZN+vqZcvKexyRqZlP1DbPjjeboI2TbqGfftUsyZu2jz5y/NRYlS9HzEijcQ==",
       "dev": true,
       "requires": {
         "bonjour-hap": "3.5.4",
@@ -273,14 +273,14 @@
       "dev": true
     },
     "homebridge": {
-      "version": "0.4.54-beta.51",
+      "version": "0.4.54-beta.52",
-      "resolved": "https://registry.npmjs.org/homebridge/-/homebridge-0.4.54-beta.51.tgz",
+      "resolved": "https://registry.npmjs.org/homebridge/-/homebridge-0.4.54-beta.52.tgz",
-      "integrity": "sha512-WycAihWBzWu+8ZBnVrU4wqdU0bq/cT43iKdk2+6ODhbGh/xlaxIFpMdSGX++YqwGpu7cNEL0L45Woj9sEfFYNw==",
+      "integrity": "sha512-fQKpd2khare7BTbzyEVjABWLhAeTUF1it5MrvnI/NDlzkvehPv362j8Jim1/sVyafbY+RloC0z5vFdu1nkNvoA==",
       "dev": true,
       "requires": {
         "chalk": "^3.0.0",
         "commander": "5.0.0",
-        "hap-nodejs": "0.6.2",
+        "hap-nodejs": "0.6.3",
         "node-persist": "^0.0.11",
         "qrcode-terminal": "^0.12.0",
         "semver": "^7.1.3",

dynamic-platform-example-typescript/package.json

@@ -30,6 +30,6 @@
     "@types/node": "10.17.19",
     "typescript": "^3.8.3",
     "rimraf": "^3.0.2",
-    "homebridge": "^0.4.54-beta.51"
+    "homebridge": "^0.4.54-beta.52"
   }
 }

dynamic-platform-example-typescript/src/dynamic-platform.ts

@@ -2,6 +2,7 @@ import http, {IncomingMessage, Server, ServerResponse} from "http";
 import {
   API,
   APIEvent,
+  CharacteristicEventTypes,
   CharacteristicSetCallback,
   CharacteristicValue,
   DynamicPlatformPlugin,
@@ -10,14 +11,32 @@ import {
   PlatformAccessory,
   PlatformAccessoryEvent,
   PlatformConfig,
-  Service,
 } from "homebridge";
 
 const PLUGIN_NAME = "homebridge-dynamic-platform-example";
 const PLATFORM_NAME = "ExampleDynamicPlatform";
 
-/**
+/*
- * TODO explain
+ * IMPORTANT NOTICE
+ *
+ * One thing you need to take care of is, that you never ever ever import anything directly from the "homebridge" module (or the "hap-nodejs" module).
+ * The above import block may seem like, that we do exactly that, but actually those imports are only used for types and interfaces
+ * and will disappear once the code is compiled to Javascript.
+ * In fact you can check that by running `npm run build` and opening the compiled Javascript file in the `dist` folder.
+ * You will notice that the file does not contain a `... = require("homebridge");` statement anywhere in the code.
+ *
+ * The contents of the above import statement MUST ONLY be used for type annotation or accessing things like CONST ENUMS,
+ * which is a special case as they get replaced by the actual value and do not remain as a reference in the compiled code.
+ * Meaning normal enums are bad, const enums can be used.
+ *
+ * You MUST NOT import anything else which remains as a reference in the code, as this will result in
+ * a `... = require("homebridge");` to be compiled into the final Javascript code.
+ * This typically leads to unexpected behavior at runtime, as in many cases it won't be able to find the module
+ * or will import another instance of homebridge causing collisions.
+ *
+ * To mitigate this the {@link API | Homebridge API} exposes the whole suite of HAP-NodeJS inside the `hap` property
+ * of the api object, which can be acquired for example in the initializer function. This reference can be stored
+ * like this for example and used to access all exported variables and classes from HAP-NodeJS.
  */
 let hap: HAP;
 let Accessory: typeof PlatformAccessory;
@@ -72,7 +91,7 @@ class ExampleDynamicPlatform implements DynamicPlatformPlugin {
     });
 
     accessory.getService(hap.Service.Lightbulb)!.getCharacteristic(hap.Characteristic.On)
-      .on(hap.CharacteristicEventTypes.SET, (value: CharacteristicValue, callback: CharacteristicSetCallback) => {
+      .on(CharacteristicEventTypes.SET, (value: CharacteristicValue, callback: CharacteristicSetCallback) => {
         this.log.info("%s Light was set to: " + value);
         callback();
       });

independent-platform-example-typescript/package-lock.json

@@ -237,9 +237,9 @@
       }
     },
     "hap-nodejs": {
-      "version": "0.6.2",
+      "version": "0.6.3",
-      "resolved": "https://registry.npmjs.org/hap-nodejs/-/hap-nodejs-0.6.2.tgz",
+      "resolved": "https://registry.npmjs.org/hap-nodejs/-/hap-nodejs-0.6.3.tgz",
-      "integrity": "sha512-/LlRaYCtcwC4jBUKRJeBUdUfKEp8w/NK3PNYXaAOngQL9uVnqsvQ0Gce/mUhSXPhsxfdnxbHVT870W9OEnV6+A==",
+      "integrity": "sha512-FH5cEBJDz1e/IzqYbGEO4PdydXrZN+vqZcvKexyRqZlP1DbPjjeboI2TbqGfftUsyZu2jz5y/NRYlS9HzEijcQ==",
       "dev": true,
       "requires": {
         "bonjour-hap": "3.5.4",
@@ -273,14 +273,14 @@
       "dev": true
     },
     "homebridge": {
-      "version": "0.4.54-beta.51",
+      "version": "0.4.54-beta.52",
-      "resolved": "https://registry.npmjs.org/homebridge/-/homebridge-0.4.54-beta.51.tgz",
+      "resolved": "https://registry.npmjs.org/homebridge/-/homebridge-0.4.54-beta.52.tgz",
-      "integrity": "sha512-WycAihWBzWu+8ZBnVrU4wqdU0bq/cT43iKdk2+6ODhbGh/xlaxIFpMdSGX++YqwGpu7cNEL0L45Woj9sEfFYNw==",
+      "integrity": "sha512-fQKpd2khare7BTbzyEVjABWLhAeTUF1it5MrvnI/NDlzkvehPv362j8Jim1/sVyafbY+RloC0z5vFdu1nkNvoA==",
       "dev": true,
       "requires": {
         "chalk": "^3.0.0",
         "commander": "5.0.0",
-        "hap-nodejs": "0.6.2",
+        "hap-nodejs": "0.6.3",
         "node-persist": "^0.0.11",
         "qrcode-terminal": "^0.12.0",
         "semver": "^7.1.3",

independent-platform-example-typescript/package.json

@@ -33,6 +33,6 @@
     "@types/node": "10.17.19",
     "typescript": "^3.8.3",
     "rimraf": "^3.0.2",
-    "homebridge": "^0.4.54-beta.51"
+    "homebridge": "^0.4.54-beta.52"
   }
 }

independent-platform-example-typescript/src/independent-platform.ts

@@ -1,5 +1,6 @@
 import {
   API,
+  CharacteristicEventTypes,
   CharacteristicGetCallback,
   CharacteristicSetCallback,
   CharacteristicValue,
@@ -13,8 +14,27 @@ import {
 const PLUGIN_NAME = "homebridge-independent-platform-example";
 const PLATFORM_NAME = "ExampleIndependentPlatform";
 
-/**
+/*
- * TODO explain
+ * IMPORTANT NOTICE
+ *
+ * One thing you need to take care of is, that you never ever ever import anything directly from the "homebridge" module (or the "hap-nodejs" module).
+ * The above import block may seem like, that we do exactly that, but actually those imports are only used for types and interfaces
+ * and will disappear once the code is compiled to Javascript.
+ * In fact you can check that by running `npm run build` and opening the compiled Javascript file in the `dist` folder.
+ * You will notice that the file does not contain a `... = require("homebridge");` statement anywhere in the code.
+ *
+ * The contents of the above import statement MUST ONLY be used for type annotation or accessing things like CONST ENUMS,
+ * which is a special case as they get replaced by the actual value and do not remain as a reference in the compiled code.
+ * Meaning normal enums are bad, const enums can be used.
+ *
+ * You MUST NOT import anything else which remains as a reference in the code, as this will result in
+ * a `... = require("homebridge");` to be compiled into the final Javascript code.
+ * This typically leads to unexpected behavior at runtime, as in many cases it won't be able to find the module
+ * or will import another instance of homebridge causing collisions.
+ *
+ * To mitigate this the {@link API | Homebridge API} exposes the whole suite of HAP-NodeJS inside the `hap` property
+ * of the api object, which can be acquired for example in the initializer function. This reference can be stored
+ * like this for example and used to access all exported variables and classes from HAP-NodeJS.
  */
 let hap: HAP;
 let Accessory: typeof PlatformAccessory;
@@ -50,11 +70,11 @@ class ExampleIndependentPlatform implements IndependentPlatformPlugin {
 
     const switchService = new hap.Service.Switch(name);
     switchService.getCharacteristic(hap.Characteristic.On)
-      .on(hap.CharacteristicEventTypes.GET, (callback: CharacteristicGetCallback) => {
+      .on(CharacteristicEventTypes.GET, (callback: CharacteristicGetCallback) => {
         this.log.info("Current state of the switch was returned: " + (switchOn? "ON": "OFF"));
         callback(undefined, switchOn);
       })
-      .on(hap.CharacteristicEventTypes.SET, (value: CharacteristicValue, callback: CharacteristicSetCallback) => {
+      .on(CharacteristicEventTypes.SET, (value: CharacteristicValue, callback: CharacteristicSetCallback) => {
         switchOn = value as boolean;
         this.log.info("Switch state was set to: " + (switchOn? "ON": "OFF"));
         callback();

static-platform-example-typescript/package-lock.json

@@ -237,9 +237,9 @@
       }
     },
     "hap-nodejs": {
-      "version": "0.6.2",
+      "version": "0.6.3",
-      "resolved": "https://registry.npmjs.org/hap-nodejs/-/hap-nodejs-0.6.2.tgz",
+      "resolved": "https://registry.npmjs.org/hap-nodejs/-/hap-nodejs-0.6.3.tgz",
-      "integrity": "sha512-/LlRaYCtcwC4jBUKRJeBUdUfKEp8w/NK3PNYXaAOngQL9uVnqsvQ0Gce/mUhSXPhsxfdnxbHVT870W9OEnV6+A==",
+      "integrity": "sha512-FH5cEBJDz1e/IzqYbGEO4PdydXrZN+vqZcvKexyRqZlP1DbPjjeboI2TbqGfftUsyZu2jz5y/NRYlS9HzEijcQ==",
       "dev": true,
       "requires": {
         "bonjour-hap": "3.5.4",
@@ -273,14 +273,14 @@
       "dev": true
     },
     "homebridge": {
-      "version": "0.4.54-beta.51",
+      "version": "0.4.54-beta.52",
-      "resolved": "https://registry.npmjs.org/homebridge/-/homebridge-0.4.54-beta.51.tgz",
+      "resolved": "https://registry.npmjs.org/homebridge/-/homebridge-0.4.54-beta.52.tgz",
-      "integrity": "sha512-WycAihWBzWu+8ZBnVrU4wqdU0bq/cT43iKdk2+6ODhbGh/xlaxIFpMdSGX++YqwGpu7cNEL0L45Woj9sEfFYNw==",
+      "integrity": "sha512-fQKpd2khare7BTbzyEVjABWLhAeTUF1it5MrvnI/NDlzkvehPv362j8Jim1/sVyafbY+RloC0z5vFdu1nkNvoA==",
       "dev": true,
       "requires": {
         "chalk": "^3.0.0",
         "commander": "5.0.0",
-        "hap-nodejs": "0.6.2",
+        "hap-nodejs": "0.6.3",
         "node-persist": "^0.0.11",
         "qrcode-terminal": "^0.12.0",
         "semver": "^7.1.3",

static-platform-example-typescript/package.json

@@ -33,6 +33,6 @@
     "@types/node": "10.17.19",
     "typescript": "^3.8.3",
     "rimraf": "^3.0.2",
-    "homebridge": "^0.4.54-beta.51"
+    "homebridge": "^0.4.54-beta.52"
   }
 }

static-platform-example-typescript/src/static-platform.ts

@@ -3,8 +3,27 @@ import {ExampleSwitch} from "./switch-accessory";
 
 const PLATFORM_NAME = "ExampleStaticPlatform";
 
-/**
+/*
- * TODO explain
+ * IMPORTANT NOTICE
+ *
+ * One thing you need to take care of is, that you never ever ever import anything directly from the "homebridge" module (or the "hap-nodejs" module).
+ * The above import block may seem like, that we do exactly that, but actually those imports are only used for types and interfaces
+ * and will disappear once the code is compiled to Javascript.
+ * In fact you can check that by running `npm run build` and opening the compiled Javascript file in the `dist` folder.
+ * You will notice that the file does not contain a `... = require("homebridge");` statement anywhere in the code.
+ *
+ * The contents of the above import statement MUST ONLY be used for type annotation or accessing things like CONST ENUMS,
+ * which is a special case as they get replaced by the actual value and do not remain as a reference in the compiled code.
+ * Meaning normal enums are bad, const enums can be used.
+ *
+ * You MUST NOT import anything else which remains as a reference in the code, as this will result in
+ * a `... = require("homebridge");` to be compiled into the final Javascript code.
+ * This typically leads to unexpected behavior at runtime, as in many cases it won't be able to find the module
+ * or will import another instance of homebridge causing collisions.
+ *
+ * To mitigate this the {@link API | Homebridge API} exposes the whole suite of HAP-NodeJS inside the `hap` property
+ * of the api object, which can be acquired for example in the initializer function. This reference can be stored
+ * like this for example and used to access all exported variables and classes from HAP-NodeJS.
  */
 let hap: HAP;
 

static-platform-example-typescript/src/switch-accessory.ts

@@ -5,7 +5,8 @@ import {
   CharacteristicValue,
   HAP,
   Logging,
-  Service
+  Service,
+  CharacteristicEventTypes
 } from "homebridge";
 
 export class ExampleSwitch implements AccessoryPlugin {
@@ -26,11 +27,11 @@ export class ExampleSwitch implements AccessoryPlugin {
 
     this.switchService = new hap.Service.Switch(name);
     this.switchService.getCharacteristic(hap.Characteristic.On)
-      .on(hap.CharacteristicEventTypes.GET, (callback: CharacteristicGetCallback) => {
+      .on(CharacteristicEventTypes.GET, (callback: CharacteristicGetCallback) => {
         log.info("Current state of the switch was returned: " + (this.switchOn? "ON": "OFF"));
         callback(undefined, this.switchOn);
       })
-      .on(hap.CharacteristicEventTypes.SET, (value: CharacteristicValue, callback: CharacteristicSetCallback) => {
+      .on(CharacteristicEventTypes.SET, (value: CharacteristicValue, callback: CharacteristicSetCallback) => {
         this.switchOn = value as boolean;
         log.info("Switch state was set to: " + (this.switchOn? "ON": "OFF"));
         callback();