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

2025-10-29 09:30:26 +00:00 · 2020-04-18 12:28:18 +02:00
parent 60f1a21529
commit ed0c930e09
17 changed files with 164 additions and 65 deletions
--- a/accessory-example-typescript/package-lock.json
+++ b/accessory-example-typescript/package-lock.json
@@ -237,9 +237,9 @@
      }
    },
    "hap-nodejs": {
-      "version": "0.6.2",
-      "resolved": "https://registry.npmjs.org/hap-nodejs/-/hap-nodejs-0.6.2.tgz",
-      "integrity": "sha512-/LlRaYCtcwC4jBUKRJeBUdUfKEp8w/NK3PNYXaAOngQL9uVnqsvQ0Gce/mUhSXPhsxfdnxbHVT870W9OEnV6+A==",
+      "version": "0.6.3",
+      "resolved": "https://registry.npmjs.org/hap-nodejs/-/hap-nodejs-0.6.3.tgz",
+      "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",
-      "resolved": "https://registry.npmjs.org/homebridge/-/homebridge-0.4.54-beta.51.tgz",
-      "integrity": "sha512-WycAihWBzWu+8ZBnVrU4wqdU0bq/cT43iKdk2+6ODhbGh/xlaxIFpMdSGX++YqwGpu7cNEL0L45Woj9sEfFYNw==",
+      "version": "0.4.54-beta.52",
+      "resolved": "https://registry.npmjs.org/homebridge/-/homebridge-0.4.54-beta.52.tgz",
+      "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",
--- a/accessory-example-typescript/package.json
+++ b/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"
  }
 }
--- a/accessory-example-typescript/src/accessory.ts
+++ b/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();
--- a/bridged-camera-example-typescript/package-lock.json
+++ b/bridged-camera-example-typescript/package-lock.json
@@ -246,9 +246,9 @@
      }
    },
    "hap-nodejs": {
-      "version": "0.6.2",
-      "resolved": "https://registry.npmjs.org/hap-nodejs/-/hap-nodejs-0.6.2.tgz",
-      "integrity": "sha512-/LlRaYCtcwC4jBUKRJeBUdUfKEp8w/NK3PNYXaAOngQL9uVnqsvQ0Gce/mUhSXPhsxfdnxbHVT870W9OEnV6+A==",
+      "version": "0.6.3",
+      "resolved": "https://registry.npmjs.org/hap-nodejs/-/hap-nodejs-0.6.3.tgz",
+      "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",
-      "resolved": "https://registry.npmjs.org/homebridge/-/homebridge-0.4.54-beta.51.tgz",
-      "integrity": "sha512-WycAihWBzWu+8ZBnVrU4wqdU0bq/cT43iKdk2+6ODhbGh/xlaxIFpMdSGX++YqwGpu7cNEL0L45Woj9sEfFYNw==",
+      "version": "0.4.54-beta.52",
+      "resolved": "https://registry.npmjs.org/homebridge/-/homebridge-0.4.54-beta.52.tgz",
+      "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",
--- a/bridged-camera-example-typescript/package.json
+++ b/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"
  }
 }
--- a/bridged-camera-example-typescript/src/dynamic-camera-platform.ts
+++ b/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;
--- a/bridged-camera-example-typescript/src/streamingDelegate.ts
+++ b/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
-          videoffmpegCommand += `-srtp_out_suite ${this.hap.SRTPCryptoSuites[cryptoSuite]} -srtp_out_params ${videoSRTP} s`;
+        if (cryptoSuite === SRTPCryptoSuites.AES_CM_128_HMAC_SHA1_80) { // actually ffmpeg just supports AES_CM_128_HMAC_SHA1_80
+          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 {
--- a/dynamic-platform-example-typescript/package-lock.json
+++ b/dynamic-platform-example-typescript/package-lock.json
@@ -237,9 +237,9 @@
      }
    },
    "hap-nodejs": {
-      "version": "0.6.2",
-      "resolved": "https://registry.npmjs.org/hap-nodejs/-/hap-nodejs-0.6.2.tgz",
-      "integrity": "sha512-/LlRaYCtcwC4jBUKRJeBUdUfKEp8w/NK3PNYXaAOngQL9uVnqsvQ0Gce/mUhSXPhsxfdnxbHVT870W9OEnV6+A==",
+      "version": "0.6.3",
+      "resolved": "https://registry.npmjs.org/hap-nodejs/-/hap-nodejs-0.6.3.tgz",
+      "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",
-      "resolved": "https://registry.npmjs.org/homebridge/-/homebridge-0.4.54-beta.51.tgz",
-      "integrity": "sha512-WycAihWBzWu+8ZBnVrU4wqdU0bq/cT43iKdk2+6ODhbGh/xlaxIFpMdSGX++YqwGpu7cNEL0L45Woj9sEfFYNw==",
+      "version": "0.4.54-beta.52",
+      "resolved": "https://registry.npmjs.org/homebridge/-/homebridge-0.4.54-beta.52.tgz",
+      "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",
--- a/dynamic-platform-example-typescript/package.json
+++ b/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"
  }
 }
--- a/dynamic-platform-example-typescript/src/dynamic-platform.ts
+++ b/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();
      });
--- a/independent-platform-example-typescript/package-lock.json
+++ b/independent-platform-example-typescript/package-lock.json
@@ -237,9 +237,9 @@
      }
    },
    "hap-nodejs": {
-      "version": "0.6.2",
-      "resolved": "https://registry.npmjs.org/hap-nodejs/-/hap-nodejs-0.6.2.tgz",
-      "integrity": "sha512-/LlRaYCtcwC4jBUKRJeBUdUfKEp8w/NK3PNYXaAOngQL9uVnqsvQ0Gce/mUhSXPhsxfdnxbHVT870W9OEnV6+A==",
+      "version": "0.6.3",
+      "resolved": "https://registry.npmjs.org/hap-nodejs/-/hap-nodejs-0.6.3.tgz",
+      "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",
-      "resolved": "https://registry.npmjs.org/homebridge/-/homebridge-0.4.54-beta.51.tgz",
-      "integrity": "sha512-WycAihWBzWu+8ZBnVrU4wqdU0bq/cT43iKdk2+6ODhbGh/xlaxIFpMdSGX++YqwGpu7cNEL0L45Woj9sEfFYNw==",
+      "version": "0.4.54-beta.52",
+      "resolved": "https://registry.npmjs.org/homebridge/-/homebridge-0.4.54-beta.52.tgz",
+      "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",
--- a/independent-platform-example-typescript/package.json
+++ b/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"
  }
 }
--- a/independent-platform-example-typescript/src/independent-platform.ts
+++ b/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();
--- a/static-platform-example-typescript/package-lock.json
+++ b/static-platform-example-typescript/package-lock.json
@@ -237,9 +237,9 @@
      }
    },
    "hap-nodejs": {
-      "version": "0.6.2",
-      "resolved": "https://registry.npmjs.org/hap-nodejs/-/hap-nodejs-0.6.2.tgz",
-      "integrity": "sha512-/LlRaYCtcwC4jBUKRJeBUdUfKEp8w/NK3PNYXaAOngQL9uVnqsvQ0Gce/mUhSXPhsxfdnxbHVT870W9OEnV6+A==",
+      "version": "0.6.3",
+      "resolved": "https://registry.npmjs.org/hap-nodejs/-/hap-nodejs-0.6.3.tgz",
+      "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",
-      "resolved": "https://registry.npmjs.org/homebridge/-/homebridge-0.4.54-beta.51.tgz",
-      "integrity": "sha512-WycAihWBzWu+8ZBnVrU4wqdU0bq/cT43iKdk2+6ODhbGh/xlaxIFpMdSGX++YqwGpu7cNEL0L45Woj9sEfFYNw==",
+      "version": "0.4.54-beta.52",
+      "resolved": "https://registry.npmjs.org/homebridge/-/homebridge-0.4.54-beta.52.tgz",
+      "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",
--- a/static-platform-example-typescript/package.json
+++ b/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"
  }
 }
--- a/static-platform-example-typescript/src/static-platform.ts
+++ b/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;

--- a/static-platform-example-typescript/src/switch-accessory.ts
+++ b/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();