diff --git a/README.md b/README.md
index 8719dca..1e344fa 100644
--- a/README.md
+++ b/README.md
@@ -12,15 +12,106 @@ allows you to connect to an MQTT broker where you can publish messages and subsc
 composer require php-mqtt/laravel-client
 ```
 
-You should then publish the configuration file using
+The package will register itself through Laravel auto discovery of packages.
+Registered will be the service provider as well as an `MQTT` facade.
+
+After installing the package, you should publish the configuration file using
 
 ```bash
 php artisan vendor:publish --provider="PhpMqtt\Client\MqttClientServiceProvider"
 ```
 
+and change the configuration in `config/mqtt-client.php` according to your needs.
+
+## Configuration
+
+The package allows you to configure multiple named connections. An initial example
+can be found in the published configuration file. Except for the `host` parameter,
+all configuration options are entirely optional and come with the defaults provided 
+to the `env()` helper in the example configuration file (no default means `null`).
+
+An example configuration of two connections, where one is meant for sharing public
+data and one for private data, could look like the following:
+```php
+'default_connection' => 'private',
+
+'connections' => [
+    'private' => [
+        'host' => 'mqtt.example.com',
+        'port' => 1883,
+    ],
+    'public' => [
+        'host' => 'test.mosquitto.org',
+        'port' => 1883,
+    ],
+],
+```
+In this example, the private connection is the default one.
+
 ## Usage
 
-// TODO: usage
+### Publish (QoS level 0)
+
+Publishing a message with QoS level 0 is quite easy and can be done in a single command:
+```php
+use PhpMqtt\Client\Facades\MQTT;
+
+MQTT::publish('some/topic', 'Hello World!');
+```
+
+If needed, the connection name can be passed as third parameter:
+```php
+use PhpMqtt\Client\Facades\MQTT;
+
+MQTT::publish('some/topic', 'Hello World!', 'public');
+```
+
+Using `MQTT::publish($topic, $message)` will implicitly call `MQTT::connection()`,
+but the connection will not be closed after usage. If you want to close the connection
+manually because your script does not need the connection any more, you can call
+`MQTT:close()` (optionally with the connection name as a parameter).
+Please also note that using `MQTT::publish($topic, $message)` will always use QoS level 0.
+If you need a different QoS level, then please follow the instructions below.
+
+### Publish (QoS level 1 & 2)
+
+Different to QoS level 0, we need to run an event loop in order for QoS 1 and 2 to work.
+This is because with a one-off command we cannot guarantee that a message reaches it's target.
+The event loop will ensure a published message gets sent again if no acknowledgment is returned
+by the broker within a grace period (in case of QoS level 1). Also handled by the event loop will
+be the release of packages in case of QoS level 2.
+
+```php
+use PhpMqtt\Client\Facades\MQTT;
+
+$mqtt = MQTT::connection();
+$mqtt->publish('some/topic', 'foo', 1);
+$mqtt->publish('some/other/topic', 'bar', 2);
+$mqtt->loop(true);
+```
+
+In order to escape the loop, you can call `$mqtt->interrupt()` which will exit the loop during
+the next iteration. The method can for example be called in a registered signal handler:
+```php
+pcntl_signal(SIGINT, function (int $signal, $info) use ($mqtt) {
+    $mqtt->interrupt();
+});
+```
+
+### Subscribe
+
+Very similar to publishing with QoS level 1 and 2, subscribing requires to run an event loop.
+But before running the loop, topics need to be subscribed to:
+
+```php
+use PhpMqtt\Client\Facades\MQTT;
+
+$mqtt = MQTT::connection();
+$mqtt->subscribe('some/topic', function (string $topic, string $message) {
+    echo sprintf('Received QoS level 1 message on topic [%s]: %s', $topic, $message);
+}, 1);
+$mqtt->loop(true);
+```
 
 ## Features