diff --git a/README.md b/README.md
index 118e385..0870a76 100644
--- a/README.md
+++ b/README.md
@@ -5,10 +5,21 @@
 
 # NeoHubAPI
 
-This is a simple python wrapper around Heatmiser's Neohub API.
+This is a simple python wrapper around Heatmiser's Neohub API. Up-to-date 
+documentation for the API can be obtained from the [Heatmiser Developer
+Portal](https://dev.heatmiser.com). You will need to sign up for a free account.
 
-It's primary purpose is to be used via Home Assistant integration but
-it can also be used as a standalone library.
+The primary purpose of this module is to help with [Home
+Assistant](https://www.home-assistant.io) integration but it can also be used as
+ a standalone library for other projects.
+
+## Connection methods
+
+The API provides two connection methods. The so-called "legacy" method is by way of an unencrypted connection to port 4242 of the Neohub. The newer method uses an encrypted websocket on port 4243, but only works on a second generation hub (look for the sticker on the back).
+
+To use the websocket connection, you need to obtain a token from the Heatmiser Neo app. Go to `Settings > API > +` in the app and create one.
+
+On newer hubs, the legacy connection may be disabled by default. If you want to use it, go to `Settings > API` in the app, and enable it from there.
 
 ## Usage example
 
@@ -18,7 +29,10 @@ import neohubapi.neohub as neohub
 
 
 async def run():
+    # Legacy connection
     hub = neohub.NeoHub()
+    # Or, for a websocket connection:
+    # hub = neohub.Neohub(port=4243, token='xxx-xxxxxxx')
     system = await hub.get_system()
     hub_data, devices = await hub.get_live_data()
     for device in devices['thermostats']:
@@ -29,10 +43,7 @@ async def run():
 asyncio.run(run())
 ```
 
-## NeoHub API documentation
 
-API documentation can be found from various places online or
-you can request the latest version from support@heatmiser.com
 
 ## neohub_cli.py