add multiple protocols server side

Author: VigneshVSV

docs/beginners-guide/articles/protocols/general.md

@@ -0,0 +1,63 @@
+# General
+
+There are multiple ways to start serving your `Thing`:
+
+- One needs to run one `Thing` in multiple protocols
+- One needs to run multiple `Thing`s in one protocol
+- One needs to run multiple `Thing`s in multiple protocols
+
+## Run Single Thing in Multiple Protocols
+
+There are two possible syntax options:
+
+```python linenums="1"
+from hololinked.server import HTTPServer, MQTTServer
+
+http_server = HTTPServer(port=9000)
+mqtt_server = MQTTServer(host='mqtt.example.com', port=1883)
+zmq_server = ZMQServer(access_points=['IPC', 'tcp://*:9001'])
+
+Oscilloscope(id='oscilloscope').run(servers=[http_server, mqtt_server, zmq_server])
+```
+
+OR
+
+```python linenums="1"
+from hololinked.server import HTTPServer, MQTTServer
+
+Oscilloscope(id='oscilloscope').run(
+    access_points=(
+        ('HTTP', 9000),
+        ('MQTT', 'mqtt.example.com'),
+        ('ZMQ', ['IPC', 'tcp://*:9001']),
+    )
+)
+```
+
+The first option is obviously preferred.
+
+## Run Multiple Things in One Protocol
+
+```python linenums="1"
+from hololinked.server import HTTPServer
+
+server = HTTPServer(port=9000)
+server.add_thing(Oscilloscope(id='oscilloscope'))
+server.add_thing(DCPowerSupply(id='dc-power-supply'))
+
+server.run()
+```
+
+## Run Multiple Things in Multiple Protocols
+
+```python linenums="1"
+from hololinked.server import HTTPServer, MQTTServer, run
+
+http_server = HTTPServer(port=9000)
+mqtt_server = MQTTServer(host='mqtt.example.com', port=1883)
+
+http_server.add_thing(Oscilloscope(id='oscilloscope'))
+mqtt_server.add_thing(DCPowerSupply(id='dc-power-supply'))
+
+run(servers=[http_server, mqtt_server])
+```

docs/beginners-guide/articles/protocols/http.md

@@ -13,14 +13,14 @@ ssl_context = ssl.SSLContext(protocol=ssl.PROTOCOL_TLS_SERVER)
 ssl_context.load_cert_chain(cert_file, keyfile=key_file)
 ssl_context.minimum_version = ssl.TLSVersion.TLSv1_3
 
-http_server = HTTPServer(port=8090, ssl_context=ssl_context)
+http_server = HTTPServer(port=9000, ssl_context=ssl_context)
 
 Oscilloscope(id='oscilloscope').run(servers=[http_server])
 # OR
 Oscilloscope(
     id='oscilloscope',
 ).run_with_http_server(
-    port=8090,
+    port=9000,
     ssl_context=ssl_context,
 )
 ```
@@ -44,7 +44,7 @@ One can register custom routes and methods as follows:
 ```python linenums="1" title="Custom Routes"
 from hololinked.server import HTTPServer
 
-server = HTTPServer(port=8090)
+server = HTTPServer(port=9000)
 
 server.add_property('/channels/data/A', Oscilloscope.channel_A)
 server.add_event('/channels/data/A/stream', Oscilloscope.channel_A_data_event)
@@ -57,13 +57,13 @@ Oscilloscope(id='oscilloscope').run(servers=[server])
 On the web browser, one may want to access the HTTP server from a different domain name, especially during development or in private networks. In such cases, one needs to enable CORS headers:
 
 ```python linenums="1" title="Enable CORS"
-http_server = HTTPServer(port=8090, config=dict(cors=True))
+http_server = HTTPServer(port=9000, config=dict(cors=True))
 Oscilloscope(id='oscilloscope').run(servers=[http_server])
 # OR
 Oscilloscope(
     id='oscilloscope',
 ).run_with_http_server(
-    port=8090,
+    port=9000,
     config=dict(cors=True),
 )
 ```

docs/beginners-guide/articles/protocols/mqtt.md

@@ -0,0 +1,25 @@
+# MQTT
+
+## SSL context
+
+To use MQTT over SSL/TLS, one needs to create an SSL context as follows:
+
+```python linenums="1" title="Use SSL"
+import ssl, os
+
+ssl_context = ssl.create_default_context(ssl.Purpose.SERVER_AUTH)
+ssl_context.load_verify_locations(cafile="ca.crt")
+ssl_context.check_hostname = True
+ssl_context.verify_mode = ssl.CERT_REQUIRED
+ssl_context.minimum_version = ssl.TLSVersion.TLSv1_2
+
+mqtt_server = MQTTServer(
+    host='mqtt.example.com',
+    port=8883,
+    ssl_context=ssl_context,
+)
+Oscilloscope(id='oscilloscope').run(servers=[mqtt_server])
+```
+
+Note that since MQTT has broker-based architecture and all publishers are clients to the broker,
+the SSL context here is created with purpose `ssl.Purpose.SERVER_AUTH`.

mkdocs.yml

@@ -25,7 +25,9 @@ nav:
       - Configuring Thing Class: beginners-guide/articles/thing.md
       - Serialization: beginners-guide/articles/serialization.md
       - Protocols:
+          - General: beginners-guide/articles/protocols/general.md
           - HTTP: beginners-guide/articles/protocols/http.md
+          - MQTT: beginners-guide/articles/protocols/mqtt.md
       - Security: beginners-guide/articles/security.md
   - API Reference:
       - Namespaces: api-reference/namespaces.md