Medcast Clinic screens

Set up a screen

Every command below is copy-and-paste — nothing needs editing. The first screen takes about ten minutes. Every screen after it takes about two.

Your console is meddcast.intelligentone.ai

That is where you sign in, name your screens, and watch them come online.

Part 0Sign in

  1. Go to meddcast.intelligentone.ai in any browser.
  2. Type your email address and click Email me a confirmation code.
  3. Open your email — a message from Medcast with a six-digit code.
  4. Type those six digits into the box on the page.
  5. You are in.

The code lasts ten minutes and works once. If it expires, click send another. There is a short wait between codes; that is the mail service, not a fault.

Part 1Set your Mac up — once, ever

Skip this whole part if you have written a card before.

1.1 — Install Raspberry Pi Imager

  1. Go to raspberrypi.com/software.
  2. Click the big Download for macOS button.
  3. Open the downloaded .dmg.
  4. Drag the Raspberry Pi Imager icon onto the Applications folder.
  5. Open Applications and double-click Raspberry Pi Imager.
  6. If macOS warns it was downloaded from the internet, click Open.
  7. In the menu bar: Raspberry Pi Imager → About Raspberry Pi Imager.
  8. It must say 2.something. If it says 1.something, download it again.
Why the version matters

Imager 1.x looks like it works and silently does not — it writes the card, says Write Successful, and the settings never take effect. It does not tell you when it has updated itself, so an old copy stays old.

1.2 — Install Node

Open Terminal (press Cmd + Space, type Terminal, press Enter), then: 

node --version
  • Prints v24 or higher → go to the next block.
  • Errors, or shows a lower number → download the LTS installer from nodejs.org, run it, then close Terminal completely and open it again. 
corepack enable pnpm

1.3 — Install the Medcast tools

cd "$HOME/Desktop/MeddCast"
pnpm install

1.4 — Make the card writer double-clickable

Thirty seconds, and it removes the Terminal from every card after this one.

Download Medcast Card Writer

Unzip it and drag Medcast Card Writer to your Applications folder, then to your Dock. From then on, writing a card is: put the card in, double-click the icon, type the path it asks for. You need to be signed in to the console for the download — it is the same practice, and the tool carries your practice's secret.

Prefer to build it yourself, or already have the repository? This does the same thing and bakes in your checkout path: 

cd "$HOME/Desktop/MeddCast"
./tools/mac-app/build.sh
Why it opens a Terminal rather than being a silent app

The card writer shows you the volume it found and waits for you to confirm before it writes anything. That confirmation is the last thing between you and a wrong disk, so it needs somewhere to appear. It is a front door onto the same tool, not a different program.

Part 2Tell the card writer where your console is

Once, ever. It is a small file on your Mac, and every Terminal window and every double-click reads it from then on. 

mkdir -p ~/.config/medcast
printf '%s\n' '{"consoleUrl": "https://meddcast.intelligentone.ai", "apiSecret": "PASTE-THE-SECRET-HERE"}' > ~/.config/medcast/flash.json
chmod 600 ~/.config/medcast/flash.json
Replace PASTE-THE-SECRET-HERE with your real secret

It is the API_SECRET line in SETUP.md in your own copy of the repository, and on the server in /opt/medcast-lite/.env. It is deliberately not printed on this page — this page is public, and that one value is also written onto every SD card, so publishing it would mean re-writing all of them.

The chmod 600 on the last line is what stops other accounts on the Mac reading it. Do not paste that block into a chat window or an email.

Nothing appears after you paste that. That is correct. Now test it:

cd "$HOME/Desktop/MeddCast"
pnpm flash --dry-run
A refusal here means everything is working

You should see your console's address, a line saying it answered and accepted your secret, and then a message saying it refused because no SD card is plugged in. That proves the tool found your settings, reached your console and was let in. It stopped only because there is nothing to write to yet.

--dry-run asks your console for nothing and creates nothing, so it is always safe to run.

Part 3Write a card

Two steps, for every screen.

Step 1 — Put Raspberry Pi OS on the card

  1. Put the SD card in your Mac (use the adapter if it is a MicroSD).
  2. Open Raspberry Pi Imager.
  3. Click CHOOSE DEVICE → pick your Pi model.
  4. Click CHOOSE OS.
  5. Scroll down, click Raspberry Pi OS (other).
  6. Click Raspberry Pi OS Lite (64-bit) — the one saying Lite and 64-bit, not the one at the top.
  7. Click CHOOSE STORAGE, then click your SD card.
  8. Click NEXT.
  9. “Would you like to apply OS customisation settings?” → click NO.
  10. “All existing data will be erased. Are you sure?” → click YES.
  11. Wait about three minutes — Writing, then Verifying.
  12. At Write Successful, click CONTINUE.
Read the size before you click a disk

Whatever you pick is erased completely. An SD card is usually 8 GB–128 GB. If something says 500 GB, 1 TB or 2 TB, that is a hard drive, not your card.

Leave the card plugged in

Do not eject it. The next step needs it mounted.

Two things people get wrong here:

  • Always pick the OS from Imager's own list. If you download a .img yourself and choose it, Imager skips the settings without telling you.
  • Always click NO at the customisation question. Everything that dialogue offers is set by Medcast instead, and setting it in both places causes problems that are very hard to see afterwards.

Step 2 — Put Medcast on the card

Double-click the Medcast Card Writer in your Dock. A Terminal window opens.

  1. It says it will create one new screen for this card.
  2. It shows you the SD card it found.
  3. It asks you to confirm — type the mount path it printed, then Enter.
  4. It writes three small files and ejects the card.

Done. Take the card out.

The card carries no name, and that is deliberate

The card is for a screen called screen-1, screen-2, and so on. You say where it is afterwards, in the console, once the television is on a wall — Part 5. Naming it now would mean deciding where a television is going days before you carry it down a corridor.

There is nothing to set up in advance. You type whatever you call the place — “Waiting room”, “Dr Patel's room” — and you can change it whenever you like.

Every card that gets written makes one more screen. A card you start and abandon partway leaves a screen behind; you can remove it from the Screens page. Stopping because there was no card in the reader costs nothing at all — the card writer looks for the card before it asks the console for anything.

Imager ejects the card when it finishes, so put it back in. You do not have to start the card writer again if you already have: it waits up to two minutes for a card.

No cable to that room? A card can be written for WiFi instead.

From the Medcast Card Writer app: type w when it asks, enter the network name and passphrase once, then write the card. The next time you open the app it shows that network — press Return to reuse it, or type w again to change it (Return keeps it; type - to go back to Ethernet only). 

cd "$HOME/Desktop/MeddCast"
pnpm flash --wifi
Asked once, kept for every card after

The network is stored on this Mac in ~/.config/medcast/flash.json. You are not retyping a passphrase per screen. Ethernet is still the design and still what every other screen uses; this is for the one outlet that has no cable to it. Once the screen is online, its network can also be changed later from the console, without touching the card again.

No Dock icon? The same thing from Terminal:

cd "$HOME/Desktop/MeddCast"
pnpm flash

Part 4Start the screen

  1. Put the SD card into the Raspberry Pi.
  2. Plug in the Ethernet cable — or skip this if the card was written for WiFi.
  3. Plug the HDMI cable into the television.
  4. Turn the television on and set it to that HDMI input.
  5. Plug in the Pi's power last.
Now wait 3–6 minutes. Nothing happens at first.

That is normal. On its very first boot the Pi joins the network, installs software, downloads Medcast and starts up. Then the television shows your content and the screen appears in your console. Only the first boot is slow; after that it starts in seconds.

There is no pairing code, and the television will not ask for one

The card already knows which screen it is — that was decided when the card was written — so there is nothing to type at the television and no code to match up. If you have set up other devices that show a code on screen and ask you to enter it somewhere, this is not that.

What you will see, if there is nothing in the playlist yet, is exactly: “Connected. Waiting for content.” That is the screen telling you it worked. Put a video in the playlist and it starts playing on its own.

Part 5Name the screen

The screen is playing and the console knows it exists — but not what it is called. This is the step that puts it on the map.

  1. Open meddcast.intelligentone.ai on your phone.
  2. It opens on Screens. Your new one is at the top, under Not named yet.
  3. Tap Name this screen.
  4. Type what you call the place — “Waiting room”, “Dr Patel's room”.
  5. Press Enter, or just tap somewhere else.

That is the whole of it. There is nothing to create in advance and no list to choose from — you type whatever you call the place, and you can change it any time by tapping it again.

Plug the Pis in one at a time

A television shows nothing that identifies it, and every screen plays the same video at the same moment — so from the console they look identical. The one that has just started checking in is the one in front of you. Plug one in, name it, then plug in the next. Doing five and then working out which is which is the way to have a bad hour.

Part 6Check it worked

  1. On Screens, your screen is now under Named.
  2. It shows a green status and a last seen time that keeps updating.
  3. Tap Change showing, then tap a video.

That screen changes — and no other screen moves. Tap Back to playlist and it returns to normal. The same panel has a plain on/off switch for the television itself, for the times a room needs to go dark without waiting for the practice's shared hours.

The rest of the screens

Repeat Parts 3 to 5 for each card. Nothing changes between them — the card writer needs no arguments, so it is Imager, double-click, confirm, then name it once the television is on the wall. Do them one at a time all the way through, for the reason in Part 5.

Writing several cards at a bench with nobody watching? --yes skips the typed confirmation: 

pnpm flash --yes

A screen's name is only ever a label. Nothing is keyed off it, so renaming one is safe at any time and costs nothing — tap the name and type over it.

If something goes wrong

“None of the mounted volumes is a card this tool can provision”

The card is not plugged in, Imager has not finished, or your Mac has not noticed it yet. The card writer waits two minutes for a card before it says this, so if you are seeing it, two minutes have already passed. Nothing was created and nothing was written. 

pnpm flash --list

That lists every disk it can see and says exactly why each was unusable. It writes nothing, so it is always safe to run.

The screen never appears in the console

Wait the full ten minutes first — first boots are slow. Still nothing? Plug a keyboard and monitor into the Pi and run: 

journalctl -u medcast-bootstrap -f

That shows what it is doing. It retries every 30 seconds forever, so a Pi switched on before the network was ready fixes itself. You do not need to re-write the card.

“MEDCAST_CONSOLE_URL and MEDCAST_API_SECRET are not set”

The settings file is missing or unreadable. The message prints the exact three commands to create it — copy those, or go back to Part 2.

I wrote a card and never used it

It left a screen behind, because asking for a card is what creates the screen. Open Menu → Screens, find it under Not named yet, and use Remove this screen. A screen that is switched on cannot be removed — unplug the television first, which is the point of the rule.

I changed something on the card after the Pi started

Write the card again from Part 3. The card is only read on the very first boot — changing it afterwards does nothing at all, with no error and no warning. Re-writing is completely fine, and it makes a new screen: name it as in Part 5 and remove the old one.

Try the push console