CoMatrix Gateway User Documentation
The CoMatrix gateway is a CoAP server which acts as a HTTP forward proxy (“cross-proxy”) and is based on aiocoap
(“The Python CoAP library) 5.
It creates valid Matrix Client-Server-API (CS-API r0.6.1) HTTP requests based on incoming CoAP requests.
By default, it listens on all addresses, and the standard CoAP port (UDP 5683).
Unfortunately, the gateway currently only supports plaintext CoAP because DTLS is only supported for CoAP clients in
aiocoap at the moment.
The IP address and port to listen on can be configured by passing CLI arguments. Caution: In case of a IPv6 link-local
address the zone identifier needs to be specified (e.g.
$ ./comatrix_gateway.py -h usage: comatrix_gateway.py [-h] [-i IP] [-p PORT] CoMatrix gateway - enables usage of the Matrix protocol for constrained IoT devices optional arguments:// -h, --help show this help message and exit -i IP, --ip IP IP address to listen on (default: ::) -p PORT, --port PORT UDP Port to listen on (default: 5683)
The gateway provides the following CoAP resources:
coap://[::]/.well-known/core- Lists all available resources
coap://[::]/register- Enables registration of a new Matrix-Synapse user
coap://[::]/login- Enables login of an existing Matrix-Synapse user
coap://[::]/join- Enables joining of a Matrix room after an invitation
coap://[::]/getmsg- Enables retrieving of the last message sent to a Matrix room
coap://[::]/send- Enables sending of a message to a Matrix room
coap://[::]/time- Non-Matrix-related resource, provides a Unix timestamp
coap://[::]/logout- Enables logout of an existing Matrix-Synapse user
By default some debugging information is logged, e.g. information contained in the CoAP request like content format and message type.
Optional: Add hardcoded access token to perform CS-API requests to Matrix Synapse HS
It is possible to optionally set a hardcoded access token in
comatrix_gateway.py (see line 73), which will be used to send HTTP requests to the Matrix
Synapse HS 6 if no access token is contained in the received CoAP request (and required in the requested resource).
This can be used to reduce the necessary packet sizes for (authenticated) CoAP requests sent (by a CoMatrix client) to
the CoMatrix gateway by >200 bytes (with Synapse versions before v1.34, see update below).
Example access token (truncated):
ACCESS_TOKEN_HC = 'MDAxZWxvY2F0aW9uIG1hdHJpeC5sb2NhbGhvc3QKMDAxM2lyMWNpZCBub25jZSA9IFN6Vbdl5ETbryPgqzPNzmuC6-QIJzUr7Brz07X8wa_XAo'
To find out the current access token of a user via Element (Matrix client) 7:
- Log in to the account you want to get the access token for. Click on the name in the top left corner, then “All Settings”.
- Click the “Help & About” tab (left side of the dialog).
- Scroll to the bottom and click on
part of Access Token.
- Copy your access token to a safe place.
In the future Synapse’s access token implementation may be adapted to use shorter (random) strings instead of macaroons
Update 17.05.2021: 8 was already merged and released with Synapse v1.34 (cf. 9). The new access token format
reduces access token length from >200 Bytes to ~50 Bytes.
Unfortunately, there are currently no unittests implemented.
CoMatrix currently provides a few Python scripts to test CoMatrix gateway behavior.
- A Running Matrix-Synapse homeserver.
- A Running CoMatrix gateway. Needs to be able to send to HTTP(S) requests to Matrix-Synapse HS.
- The correct CoMatrix gateway and Matrix-Synapse URL needs to be set in the script file.
This list enumerates all available test scripts and their purpose:
comatrix_gateway_registration_logout_test.py: This script generates a random username and password (=username). This user is then registered at a Matrix-Synapse HS by sending a CoAP request to a CoMatrix gateway. The generated access token for this user (after successful registration) is then used to test the LogoutResource of the CoMatrix gateway.
comatrix_gateway_login_test.py: This script tests the login of an existing Matrix-Synapse user by sending a CoAP request to a CoMatrix gateway.
comatrix_gateway_getmsg_test.py: This script tests the receiving of the last message of a Matrix room by sending a CoAP request to a CoMatrix gateway.
comatrix_gateway_send_test.py: This script tests the sending of a new message to a Matrix room by sending a CoAP request to a CoMatrix gateway.
comatrix_gateway_join_test.py: This script tests the joining of a Matrix room after a user received an invitation from another user, by sending a CoAP request to a CoMatrix gateway.
- Python 3.7 (or newer)
- Python modules:
pip install -r