My (Social) Data Space

Connect a tool or machine

Last updated: 3 October 2026

A connected tool adds readings from a camera system, sensor hub, server or script to a topic on your phone. It runs separately, has its own key, and can use only the topic, fields, rate and end date you approve.

Setting one up is four steps and one download. There is nothing to build and no source code to fetch.

On your computer The connector
What it isOne Python file that reads your machine and speaks to your phone.
What it needsPython 3 and one package. No app source, no Flutter, no build.
Between the two A private connection
What it isAn invite you copy on the phone and paste into the connector, once.
What it needsBoth devices on the same private network. Nothing goes outward.
On your phone The permission
What it isThe topic, fields, rate and end date you pick when you review it.
What it needsYour approval. The connector cannot widen it later.

What you need

  • A computer that can reach both the machine and the phone on the same private network — a laptop, a home server, a Raspberry Pi. The connector does not run inside the phone app.
  • Python 3.9 or newer. macOS and Linux already have it; on Windows install it from python.org.
  • The machine’s address and, if it asks for one, a sign-in.

1. Get the connector

Download mds-connector.zip — or read mds_connector.py first, which is the whole program.

Unzip it, then in that folder:

python3 -m pip install --user cryptography
python3 mds_connector.py check

check proves the connector’s encryption against its published test vectors and confirms every refusal it relies on. It should print that everything checks out. If it prints anything else, stop there.

2. Make the topic

python3 mds_connector.py profiles
python3 mds_connector.py fields --profile frigate

profiles lists the machines the connector already knows — Frigate over HTTP or MQTT, Home Assistant sensors, Zigbee2MQTT, Plex, Streamystats, GitLab and Ollama. fields prints the topic to create in the app: open Explore and tap Create a topic (the plus at the top). Neither reads your machine and neither writes anything.

3. See what it would add

Put the machine’s address and sign-in in a file only you can read, ~/.mds-connector/credentials:

link: https://camera-system.local
user: bridge-reader
password: replace-this

Then:

python3 mds_connector.py preview --profile frigate

This signs in to the machine and prints the exact entries it would add. It does not contact your phone and writes nothing anywhere. This is the step worth spending time on: if the values or units look wrong, fix them here.

4. Connect it

In the app open My data → Tools → Connected tools → Create private invite, choose your phone’s private network, and copy the invite. Keep that screen open, then:

python3 mds_connector.py connect --profile frigate \
    --topic '<topic id>' --invite '<paste the whole invite>' --every 30

The connector prints a verification code, and your phone shows the tool’s name, the same kind of code and what it is asking for. Approve only if the two codes are exactly the same — anybody who saw the invite could answer it under the same name, but not with your connector’s code. If your phone says more than one tool answered, choose the one whose code your connector printed, or cancel and create a new invite. Then pick only the topic and fields it needs, set a sensible rate and an end date, and approve. From then on it carries readings every thirty seconds.

The invite also carries a fingerprint of your phone’s identity, and the connector offers itself to no other device that answers at that address.

To start it again later — after a reboot, or when you stopped it:

python3 mds_connector.py run --profile frigate --topic '<topic id>' --every 30

It remembers your phone’s address, so there is nothing to type again. The app must be open while readings are being carried. Pause or disconnect the tool at any time from My data → Tools → Connected tools.

Keep the connector’s own file

The connector keeps its key and its progress in ~/.mds-connector/<topic>.json. Treat that file as a secret and back it up. The permission on your phone was issued to the key inside it, so losing it means connecting again and approving again.

Adding another machine

Each machine the connector knows is one small JSON file in profiles/. Copy the closest one and change only its address, sign-in, which records to read, and how a record becomes an entry. Then run fields and preview again before you connect anything.

The mapping vocabulary is deliberately small — read some text, read a number, measure a duration, join a list, count things, use a fixed value. If a machine needs a rule the connector does not know, it is not safe to hide that behaviour in a settings file.

When it does not work

  • “That is not a usable invite.” Copy a fresh one, including the whole mds-tool-invite.v2. beginning. A v1 invite comes from an app that needs updating. Invites are short-lived and only one connection at a time is allowed.
  • It cannot reach the phone. Keep the app open and put both devices on the same private Wi-Fi or wired network. Guest Wi-Fi usually blocks devices from reaching each other.
  • preview reads nothing. Check the machine’s address and sign-in before involving the phone at all. Nothing about your phone can cause this.
  • Every reading is refused as out of scope. The topic or fields do not match what you approved. Disconnect the tool on the phone and connect it again with exactly the right topic.
  • It says it is not connected any more. Restore its ~/.mds-connector/ file from a backup. Deleting that file creates a new identity, which needs a fresh invite and a fresh approval.
  • pip is not found on Windows. Use py -m pip install cryptography and py mds_connector.py instead of python3.

The connector carries only what its profile maps and what you permitted. It never turns the machine itself into something your phone trusts, and it never makes a machine’s cloud account part of your account.