What's-a matter you? Hey!
Gotta no respect?
What-a you t'ink you do, why you look-a so sad?
It's-a not so bad, it's-a nice-a place

(If you just want to know about how to make your own Matter device in software and don't want to read a whole story to get to that point, then first of all that's, I mean, that's fine, it's not a problem, you go ahead, I'm not hurt at all, definitely not, and secondly skip down to Part 4 or check out the Github repo. But, I mean, really? You're that busy? You might wanna find a way to chill out a bit. Have a cup of tea. Enjoy life. It's better, I promise.)

Part the first: the kingdom of the blind

I've got new window blinds in my flat. They're pretty cool; ivory and purple, we're all very pleased. They're from Hillarys, who don't get a link because although the actual blinds are great, their customer service is... less so, so I'm loath to recommend them. But one of the neat things about them is that they're electrically operated. There's a remote control; press the up or down button and they go up and down. Some people would be like a fascinated small child with this technology and spend half of the first day just pressing the buttons and giggling, but not me, no no.

One of the questions I was asked when speccing them out was: do you want them to be controllable by Alexa? And I thought: well, yes, I would like that. Being able to command my blinds to open or close is one more step on the quest to be a James Bond villain. All I need after that is a monorail and a big picture on the wall which revolves to show my world domination map and I'm golden.

But... I do not like or trust the IoT industry. I'm not entirely against the whole concept -- I mean, I have an Amazon Echo, after all. It gets used for cooking timers, my shopping list, and music¹, but it doesn't get used for IoT stuff because I don't have any. This is, basically, because the whole IoT industry is full of grifters and thieves and I do not trust them with my data or with still being around in two years. The whole idea that I speak to a thing in my flat, that thing routes my command up to some server run by an IoT vendor, and then the IoT vendor's server speaks to another thing in my flat to make it do work... this is a stupid plan. It's the vendor forcibly inserting themselves as a middle man for literally no reason other than to exploit me later. Because they'll get bored or bought in a few years and they'll shut down the servers, with a sorry-not-sorry email about how it's "no longer viable to support" a thing I paid for and therefore they're turning it into a brick, but I can buy a replacement for the low low cost of... anyway, I'm not doing it. No. I don't want some random vendor's server to punch a hole into my internal network, I don't want my stuff to stop working if they turn their servers off or they go down, and the whole concept is hugely irritating.

(You might be thinking: why do you have an Echo at all, then? That's got all the same problems! And you're not wrong. But I trust Amazon to still be around for a while. Trusting them with my data is another thing, of course, but I'm already on board with that... although I entirely sympathise with people who choose to not do so either from distrust or from objections to their crappy employment or sales practices.)

Anyway, I looked up these blinds and the Alexa integration they do comes via a company called Somfy. Their APIs seem semi-reasonably documented and I've heard nothing specifically bad about them as a company... but I still don't like the idea. If I were Matthew Garrett then I would probably find joy in reverse-engineering whatever the protocol is and making it work for me, but I'm not as clever as he is². And they'll get bored or bought: I'm not sure I trust them to keep their servers running for years and years. Maybe I'd be OK with a thing that required an internet connection to someone else's server and only let me fiddle with that to the extent that I am given permission for³, if I'd only expect to keep that thing for a short time, but these are window blinds. How often do you change your window blinds? I expect these will still be here in twenty years! Do I expect these servers to also be there that long? Hell no. So, I'm not doing that.

Part the second: keep government local

I do actually have one "IoT" device in my flat, though. It's a remotely-controllable wall socket. It's from a company called LocalBytes, and it's basically a "smart plug": it's a cylinder that plugs into a wall socket, and has another socket on the other side of it, rather like one of those mini gangplug cube things.

It contains a little microcontroller and wifi chip, and it runs software called Tasmota. And it's entirely locally controlled; you get a Tasmota app (or talk the documented protocol yourself from code) which can send the plug a command to turn on and off (and also a bunch more complex stuff such as turning on at a specific time), and it involves no internet servers at all. I can't get screwed by you turning off your servers (or failing to secure them properly) if there aren't any⁴. Now, I would not recommend these Tasmota devices to a normal person; the app is unreliable and pretends it can't find the device some of the time, and the configuration API is obscure and weird. But I am, as has been said by kings and queens, not a normal person. I'm a computer bloke. So I am OK with this, and I'd be OK with something similar to control my blinds; something that runs locally and accepts commands from Alexa and then talks to the blinds to open and close them.

Now, the bit that actually talks to the blinds, I haven't started working on yet. As far as I can tell from reading, the remote control works on a standard "smart home" frequency of 433MHz, and there are loads of little dongles and boards that plug into USB or Raspberry Pi GPIO pins which can talk that. I'll get to that eventually; once I have a working thing, making it talk 433MHz is step 2. Step 1 is to make something that I control and which Alexa can talk to, but which doesn't require servers on the internet to make it work. This rules out writing a custom Alexa skill; I can do that, and have, but you can't write a skill which makes the actual Echo in my flat do network connections. The connection comes from Amazon's servers, which means I'd have to put my little device on the internet, which I don't want to do. The concern of the servers going away doesn't apply here -- if Amazon's servers go away, my Echo stops working anyway and all of this is moot -- but I do not want to punch a hole into my internal network from outside, and I shouldn't have to. This is one thing in my house talking to another thing in my house.

This problem used to be unsolvable. And then, just like in the beginning of all things, someone invented Matter.

Part the third: does it Matter?

It is, obviously, stupid that every device invents its own protocol to talk to it, and none of it's documented, and none of it's standardised, and everything gets reinvented from scratch by programmers who clearly have their minds on lunchtime. So, equally obviously, the way to solve this is to have all the biggest tech companies in the world collaboratively agree on a standard way to do things.

I can hear you laughing from here.

This has, equally equally obviously, resulted in a disastrous nine-way collision of corporate speak, absurd specifications, paywalls for things, requirements to sign up as a "partner" before you're told anything, and documentation by press release. But to my surprise it has actually resulted in something! The Matter specifications have basically everybody on board -- Amazon, Apple, Google, most of the big players in the device world -- and have finally started to actually appear in real shipping products rather than only in conference talks. The Amazon Echo supports Matter back to the 3rd gen Dot (there's a list of Matter-supporting Echo devices here). If you've got a Matter-supporting thingy, then it'll have the Matter logo on it:

and then you can say "Alexa, discover devices" and your Echo will search and then say "I have found a Matter device!". You then use the Alexa app on your phone to pair it, either by scanning a QR code or typing in a code, both of which should be on the device itself.

Now, Matter is a big corporate spec and wants to deal with all sorts of complicated and detailed edge cases. In particular, there is a standard problem with an IoT device in your house, which is that you can't talk to it until it's on the wifi, but you can't put it on the wifi without talking to it. This normally involves the device pretending to be a wifi access point, and you connecting to it with a mobile app you have to install⁵, but Matter attempts to improve this; a Matter device can potentially exchange data over wifi, over Bluetooth, over some extra network thing called Thread that I don't understand, over ethernet, the works. A lot of the setup and spec for Matter involves dealing with all this.

I, personally, for myself, for this device, do not care about this. If I were making a device that would be sold to real people, I'd implement all this stuff. But since it's just me, I'm OK with requiring that my window blind device is already on my wifi, and getting it that way is my problem, before I try detecting it with Alexa.

So, I need a way to make a Matter device; it only has to deal with wifi. The Matter specification⁶ describes how to talk Matter⁷, but there's a lot of detail in there. Surely someone has already implemented this stuff?

Well, they have... but it's not great. The @project-chip/connectedhomeip Github repository, named back in the days when Matter was still called "project CHIP" before the Branding People got their hands on it, is the reference implementation. And it's a nightmare. It's all in C, it's huge (I checked out the repo and all its submodules and ran out of disk space; to get the repo and all sub-repos and then build it, you'd better have 30GB or so free), compiling it all is a massive headache, it contains code for all sorts of different single-board computers to make them Matter devices, and I couldn't make head nor tail of it. I'm sure you need all this if you're looking to build a device and ship millions of them to people in Best Buy and Currys, but I ain't. Normally, people write stuff like this in Python, but in looking around all I could find was a Python library designed to work with Home Assistant, which is not what I wanted (I want to make a device, not a controller) and which required the CHIP SDK anyway, the big complicated nightmare thing mentioned above. I resigned myself to having to write a very noddy implementation of enough of Matter's pairing and communications stuff in Python to get a device up and running, and bitched about having to do this on social media. And then Alan Bell, hero of the revolution, said: have you tried matter.js?⁸

I had not. So I gave it a look.

Part the fourth: yes it Matters!

Matter.js is an implementation of the Matter suite of protocols in JavaScript. It does not build on the huge complicated Project CHIP SDK; it's its own thing. And it just works.

If you want to build a Matter device in JavaScript, take a look at the Matter.js Node examples and they work fine. You can do that right now.

I did something a little tiny bit different. The Matter.js stuff is not actually JS; it's TypeScript. I don't like TypeScript⁹ and so I wanted a plain JS thing. So I did a simple reimplementation of the simplest Matter.js example in plain JS, and made it even simpler; the original correctly lets you pass in a bunch of details on the command line to configure it, but I'm not bothered about that and wanted to keep it as simple as possible. So, the simplest possible "virtual" Matter device implemented in JavaScript. It's a lightbulb; Alexa, and Matter, do support multiple types of devices (including window blind controllers!) but Matter.js only does lightbulbs and sockets at the moment. I'm probably going to build and contribute the window blind controller device type, if someone else doesn't get there first. Anyway, let's get this code running! Use is pretty easy for a developer:

$ git clone https://github.com/stuartlangridge/simple-js-matter-device.git
Cloning into 'simple-js-matter-device'...
remote: Enumerating objects: 11, done.
remote: Counting objects: 100% (11/11), done.
remote: Compressing objects: 100% (10/10), done.
remote: Total 11 (delta 0), reused 7 (delta 0), pack-reused 0
Receiving objects: 100% (11/11), 25.16 KiB | 1.48 MiB/s, done.
$ cd simple-js-matter-device
$ npm install

added 90 packages, and audited 91 packages in 5s

5 packages are looking for funding
  run `npm fund` for details

found 0 vulnerabilities
$ node sil.mjs 
2023-10-06 11:38:24.231 INFO  Device               node-matter
▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄
█ ▄▄▄▄▄ ██▀▄▀▄█ ▄▄▄▄▄ █
█ █   █ █▄▀▄▀▄█ █   █ █
█ █▄▄▄█ ██ ▀▀▄█ █▄▄▄█ █
█▄▄▄▄▄▄▄█ █ ▀▄█▄▄▄▄▄▄▄█
█ ▄ █▄ ▄▄▄█ █  ▄▀██ █▀█
██▀  █▀▄█▄ █ ▀▀▄█  ▀█▀█
██▄█▄▄█▄▄█▄▄▀ ▀▄ █▄▀▄▀█
█ ▄▄▄▄▄ █  ▄█▄█▄▄ ▄ █ █
█ █   █ █▄▄ █▄ ▄ ▀▄ ▀██
█ █▄▄▄█ █  ▀█▄█ ▀█  ▀ █
█▄▄▄▄▄▄▄█▄███▄██▄██▄█▄█
▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀

2023-10-06 11:38:24.330 INFO  Device               QR Code URL: https://project-chip.github.io/connectedhomeip/qrcode.html?data=MT:Y.K90-Q000KA0648G00
2023-10-06 11:38:24.330 INFO  Device               Manual pairing code: 34970112332

We've git cloned the repository, done npm install to install the dependencies, and run it. That starts up our virtual device, and also prints the QR code and manual pairing code used for pairing. Job done; your device now exists.

Next, we teach Alexa about it. Exercise your most commanding voice and say "Alexa, discover new devices!" Your Echo will tell you it's doing it, and then after a few seconds of searching, tell you that it's found one Matter device and send you off to the devices section of the Alexa app on your phone to connect it up; I also got a notification on my phone telling me the same thing.

Hit that notification and you end up on the Devices screen, where it'll tell you to "Connect your Matter Light Bulb":

(For some reason, my device seems to present as two separate devices; a light bulb and an unnamed "Matter device". I don't know why. It seems that you can pick either.)

Choose to connect to this Matter device, and you get a screen called "Control your Matter device with Alexa", which is exactly what we want to do:

When asked if your device has a Matter logo, say yes (it would do if it were a real Matter device, of course):

Then you have to scan the QR code. Usefully, the device has printed out a QR code in the Terminal where you ran it, above; scan that. If that didn't work for some reason, it has also printed a URL for that QR code which you can follow to show the QR in the browser, and if that doesn't work either, you can enter the numeric code it printed (the "manual pairing code) instead:

Alexa will then claim to be "Looking for your device" (and the stuff in the Terminal will print a bunch of logging things about "Pase server: Received pairing request from udp://192.168.1.103:5541" and whatnot):

and then, all else being good, you'll get a screen telling you your light is connected! It's called "Kryogenix Light" in this screen, and "Stuart Light" elsewhere; you can see those strings in sil.mjs and can customise them to your heart's content.

You should now have a "Lights" section in the Devices screen of your Alexa app. You can use this to turn the "light" on and off from the Alexa app, or you can say "Alexa, turn Stuart Light on" to do it by voice. When you do that, the Terminal should print !!!!!!!!!!!!!!!! GOT COMMAND true (or false), which means it's calling the onOffListener we defined in sil.mjs. You can customise this to do whatever you'd like!

And that's it working. That's a software device, which you can pair with Alexa and customise how you choose; it doesn't require you to write an Alexa skill, and the device does not need to be accessible from the internet. That's just what I want.

Now I suppose I have to make it do something useful...

1. less so music than before, after the bloody shysters at Amazon decided to take away the free music playing from Amazon Prime and make people pay extra for it ↩
2. I make up for it by being, like, twice his size, though ↩
3. honestly, this is the big issue. I react very badly to stuff where I ought to be able to do a thing and I'm not permitted to do so because they don't want me to or can't be bothered to implement it, and won't let me do it myself. This is one of the big things that makes me move away from iOS every few years ↩
4. insert picture here of that bloke tapping his temple knowingly ↩
5. you should not need a mobile app to connect to a device pretending to be an access point. You should be able to do this from the web browser on your phone. But you can't, as I have laboriously discussed before in these pages and am still annoyed about ↩
6. as usual with corporate technology things, the Matter specification is difficult to find; one of these things where you need to sign up, or be a "partner", or pay money, or something. But it is obtainable. The Alexa Matter docs link to a page on the Matter website which lets you fill in an email address and then emails you a link to a PDF of the spec in all its 895 page glory ↩
7. super reassuringly, Matter seems to use all standard protocols! device discovery is mdns! They even have example commands for avahi-publish-service to show you how to do it, right there in the spec! ↩
8. There is an unfortunate naming collision here. There already was a Matter.js: it's a 2d physics engine for the web, which I've used before. But I can't see what else the people implementing the Matter spec in JavaScript could have called their thing. Only so many words in the world, I guess ↩
9. feel free to email your long diatribe about why TypeScript is the future to IDontCare@Whatever.Bored ↩