Artemis - REST API & Offline Devices

Toit

#Artemis - REST API & Offline Devices

Thread channel in help

bpmct 05/05/2025 09:33 PM

I am interested in allowing devices to be offline for a large amount of time (e.g. hours, days, months) but when plugged in, they re-join the fleet and may even fetch OTA updates. I also want to be able to programmatically query an API to understand which devices are offline or offline?

For the offline length, it seems like I just need to set max-offline to a very long number. However, I'm not sure if artemis has the built-in capability to query whether something is on or off, besides looking at events.

Is there a REST API I should be programmatically querying, or should I be sending health to artemis via events, or using an external backend to keep track of devices and health?

Thanks!

bpmct 05/05/2025 09:35 PM

Ah, it looks like artemis fleet status answers my question about offline. Is there a REST API reference anywhere?

bpmct 05/05/2025 10:56 PM

I'm in the process of reverse engineering that binary endpoint/function right now....

Another question:
- Should I use the cloud artemis (I am more than happy to support) or is that going away? I can deploy it myself but am also more than happy to support toit/artemis via the cloud if there are plans to continue supporting it

bpmct 05/06/2025 12:02 AM

Here is how I got the device status stuff using binary API: https://gist.github.com/bpmct/1f7ca6387b3b34ccafdec31a5c88359c(edited)

simple-devices.js

GitHub Gist: instantly share code, notes, and snippets.

floitsch 05/06/2025 07:00 AM

It looks like you managed to find answers to most of your questions by yourself.
We don't really have a rest API for the broker yet. The CLI has a way to print JSON, but the broker is currently a bit of a black box.
You already reverse engineered the protocol, but for future reference: the code is open source in the Artemis repository: https://github.com/toitware/artemis/blob/main/public/supabase_broker/supabase/functions/b/index.ts(edited)

artemis/public/supabase_broker/supabase/functions/b/index.ts at mai...

Contribute to toitware/artemis development by creating an account on GitHub.

floitsch 05/06/2025 07:03 AM

I have plans to add a broker-communication abstraction to Artemis, so that it becomes pluggable (allowing other broker implementations). I might implement a rest protocol at that point for the cli<->broker communication.(edited)

OPbpmct

I'm in the process of reverse engineering that binary endpoint/function right now.... Another question: - Should I use the cloud artemis (I am more than happy to support) or is th...

floitsch 05/06/2025 07:08 AM

We have no intention of stopping the Artemis broker, and you are welcome to use it. Especially with such a low volume of requests.
We always recommend adding a recovery URL to your devices, so they can connect to a different broker if the primary somehow disappears.
With your volume we don't have a preference for whether you use ours or yours. Choose what works best for you. And you can always migrate to a different one in the future.

bpmct 05/06/2025 02:51 PM

Awesome, thanks! I was using that code to “reverse engineer”

Great to hear that you’re adding a broker abstraction. I’m using the function now so that my tiny SaaS can track which devices are offline. It’ll probably query GitHub for the list of devices haha, or I’ll have them duplicated in a DB

Down the road, I imagine I’d want to manage my devices out of git and in a database table, but I’m actually finding it quite nice since I have to run the flash command anyways, it updates the source of truth.

At larger scales however I imagine folks flashing via WebUSB or something and it being in a central database / ui(edited)

floitsch 05/06/2025 02:53 PM

To us, the broker is just a transport channel. Whether it's a Supabase broker, or even just a simple static web-server doesn't really matter.

floitsch 05/06/2025 02:53 PM

The important data is local (which is why we recommend to check it in).

floitsch 05/06/2025 02:53 PM

If a server goes down, a simple artemis fleet roll-out uploads all important data again.

floitsch 05/06/2025 02:54 PM

Now it just happens, that we can log when a device fetches data, and we use that, but it's not critical information.

floitsch 05/06/2025 02:54 PM

In my head I have a broker implementation that uses GitHub's pages. No need for any additional server.

floitsch 05/06/2025 02:55 PM

Another one could use Cloudflare which has a simple database.

bpmct 05/06/2025 02:55 PM

Makes sense

floitsch 05/06/2025 02:59 PM

Just reread your comment.
I think I will start with abstracting the broker communication, but it shouldn't be too hard to also abstract away the local data. In that case you could then just store it in a DB.

floitsch 05/06/2025 02:59 PM

It's not very high priority, though. (unless someone depends on it)

floitsch 05/06/2025 03:00 PM

What I like about git is, that it's easy to do a revert. Once DBs are in play, that becomes much harder.

bpmct 05/06/2025 03:02 PM

Yeah that’s far less pressing for me.

The main thing I was looking for was a programmatic way of understanding the “status” of my fleet (e.g. which devices are online, who owns them, and k/v config set by the users).

Right now the info is across a few sources (git, DB, and the broker binary endpoint) but it all will work and maybe it’s not a bad thing the state is fragmented

For now I’ll continue to use git for the fleet, devices, and pods, my database for the device config (these aren’t actually impacting how the device works but instead which messages get sent to it), and the binary endpoint for the online/offline status

19 messages in total