Updating an ARTiMiS with no internet connection

This guide is for updating an instrument that is not connected to a network — the update travels on a USB stick instead.

It assumes you have used a terminal before, but not often enough to remember the details. Every command is written out in full, and every command is shown with the output you should expect back. Nothing here requires you to already know Linux.

Time needed: about 10 minutes on the instrument, plus the download.

The short version, if you have done this before:

cd /media/artimis && ls && cd STICKNAME && cd ARTIMIS-UPDATE && ls
cat ../ARTIMIS-SIGNING-KEY.txt
bash install.sh --dry-run --trust-fingerprint SHA256:<fingerprint>
bash install.sh --trust-fingerprint SHA256:<fingerprint>

Everything below is that, explained.

1. Before you start: get the fingerprint

Sign in to PhycoSight on any computer with internet access and open the Software page. Find the release, and note two things:

• the SHA-256 of the download (used in step 2), and
• the signing key fingerprint, which looks like SHA256: followed by a long string of letters and numbers.

Keep that page open — you will need the fingerprint again in section 3, where you will save it onto the USB stick so you never have to type it by hand. There is a Copy button next to it on the page; use that rather than selecting it with the mouse, since a fingerprint is long and a single missing character will cause a refusal.

Why not just read the fingerprint out of the package?

Because then it would prove nothing. The fingerprint is what tells the instrument that the package genuinely came from Skopii. Anyone who could hand you a forged package could put a matching forged fingerprint inside it, and the check would pass. The number is only meaningful when it reaches you by a route the package cannot influence — the website, over an encrypted connection.

This is also why the installer refuses to run the very first offline update without --trust-fingerprint. It will not silently trust whatever it was handed.

2. Download and verify

Download the .zip from the Software page. It is large — roughly 200 MB — because it carries everything the instrument needs to update with no network at all, including a full copy of the software history and all its Python dependencies.

Check that the download is intact before it goes anywhere near the instrument:

Windows — open PowerShell in the download folder:

certutil -hashfile artimis-airgap-production-vX.Y.Z.zip SHA256

macOS or Linux:

shasum -a 256 artimis-airgap-production-vX.Y.Z.zip

Compare the result with the SHA-256 shown on the Software page. They must match exactly. If they do not, download it again — do not continue with a file that failed this check.

3. Put it on a USB stick

Use a stick with at least 1 GB free.

3.1 Extract the update into a folder of its own

Make a new, empty folder on the stick — ARTIMIS-UPDATE is a good name — and extract the zip’s contents into it. When you are done it should look like this, with install.sh sitting directly inside the folder you made:

E:/
|---ARTIMIS-UPDATE/          <-- new folder holding the update
|   |---payload/
|   |---install.sh
|   |---README.txt

If instead you find ARTIMIS-UPDATE/artimis-airgap-production-vX.Y.Z/install.sh, your extractor added a wrapper folder. That is harmless — you will just need one extra cd in section 5 — but moving the contents up one level now makes the rest simpler.

3.2 Bring the fingerprint with you

You will need the signing key fingerprint while standing at the instrument, and the instrument has no way to reach the website. Rather than copying a 50-character string onto paper and typing it in, put it on the stick:

1. On the Software page, click Copy next to the signing key fingerprint.
2. Make a new plain text file on the stick called ARTIMIS-SIGNING-KEY.txt (any name you will recognize is fine).
3. Paste the fingerprint into it, then save and close.

Save it next to the update folder rather than inside it — that keeps it one short command away once you are in the terminal:

E:/
|---ARTIMIS-UPDATE/
|---ARTIMIS-SIGNING-KEY.txt

If you put it somewhere else, that is fine too — you will just need a different path in section 6. Anywhere on the stick works.

3.3 Move the stick to the instrument

Eject the stick safely, then plug it into the instrument.

Leave the stick plugged in for the whole update. The instrument installs its software dependencies directly from it. Pulling it out partway causes a clean automatic rollback — nothing breaks — but you will have to start over.

4. Open a terminal on the instrument

Either:

• click the Terminal icon in the taskbar, or
• press Ctrl+Alt+T.

A window opens with a line of text ending in $. That is the prompt: it is waiting for you to type a command. Type or paste one command, press Enter, wait for it to finish, then do the next one.

Pasting into a terminal is not Ctrl+V

This catches almost everyone.

Plain Ctrl+V does not paste in a Linux terminal. Instead it usually inserts junk that looks like one of these:

[[2~
^[[200~

If you see anything like that on your line, the command is corrupt. Press Ctrl+C, which abandons the line without running it and gives you a fresh prompt, then try the paste again with Ctrl+Shift+V.

Do not press Enter and hope. A corrupted command will usually fail with a confusing error, and occasionally do nothing at all while looking like it worked.

Two other things worth knowing

• Everything is case-sensitive. install.sh and Install.sh are different files.
• Tab completes names. Type the first few letters of a name and press Tab — the terminal fills in the rest. This is faster than typing and it cannot misspell anything.

5. Move into the USB stick

Run these one at a time.

5.1 — Go to where USB sticks appear:

cd /media/artimis

Nothing is printed if it worked. Silence means success — that is normal for cd.

If you get No such file or directory, the account name on this instrument is different. Run ls /media and use the name it prints instead of artimis.

5.2 — See what is plugged in:

ls

You will get something like:

FEDB-D579

That is your stick. The name varies — it might be a label like ARTIMIS-UPDATE or a string of letters and numbers.

5.3 — Move into it, replacing FEDB-D579 with whatever your stick is called:

cd FEDB-D579

5.4 — See what you put on the stick:

ls

You should see both things from section 3:

ARTIMIS-SIGNING-KEY.txt  ARTIMIS-UPDATE

5.5 — Move into the update folder (use your own folder name if you chose a different one):

cd ARTIMIS-UPDATE

5.6 — Confirm the installer is here:

ls

README.txt  airgap.manifest.json  airgap.manifest.json.sig  allowed_signers  install.sh  payload

install.sh must be in that list. If it is not:

• If you see a single folder name instead, your extractor added a wrapper — cd into it and run ls again.
• If you are lost, cd .. moves you back up one level so you can look around and try again. Nothing you do with cd and ls can change anything — they only move and look.

6. Check the package without changing anything

This step is completely safe. It runs every verification and changes nothing at all.

6.1 — Put the fingerprint on screen so you can copy it. If you saved it next to the update folder in section 3.2:

cat ../ARTIMIS-SIGNING-KEY.txt

cat just prints a file. The ../ means “look one folder up” — the stick’s top level, where you saved the key. It will print something like:

SHA256:is5a774/0GzauNt0wyRnLGiSQ2LKW6dAkBoa6KlKiKM

Select that text with the mouse and press Ctrl+Shift+C to copy it. (On most systems selecting is enough on its own, but Ctrl+Shift+C is never wrong.)

6.2 — Run the check. Paste the line below, then replace the word PASTE-FINGERPRINT-HERE with the fingerprint you copied (Ctrl+Shift+V). Keep the SHA256: that is part of the fingerprint itself:

bash install.sh --dry-run --trust-fingerprint PASTE-FINGERPRINT-HERE

The finished command looks like this:

bash install.sh --dry-run --trust-fingerprint SHA256:is5a774/0GzauNt0wyRnLGiSQ2LKW6dAkBoa6KlKiKM

Expect output like this:

ARTiMiS offline update installer
Package: /media/artimis/FEDB-D579/artimis-update

Config:    /home/artimis/.config/artimis/update.env
Runtime:   /home/artimis/.artimis
Channel:   production
Ownership: OK (runtime dir and caller are both uid 1000)
Trust:     package anchor, fingerprint confirmed (SHA256:...)
Signature: VERIFIED (skopii-release)
Package:   v1.2.0 (production)
Contents:  all files match their signed digests (203 MiB)
Disk:      OK (46913 MiB free)
Device:    idle
Target:    9d52a253 (currently 80b727fe)
Deps:      offline wheelhouse from the package

DRY RUN COMPLETE — every check passed and nothing was changed.

Three lines are worth reading carefully:

• Trust: — the fingerprint here must match the one on the website.
• Signature: VERIFIED (skopii-release) — the package is genuinely Skopii’s.
• Deps: — either offline wheelhouse from the package or unchanged (uv.lock identical to this device's). Both are normal. Which one you get depends only on whether this release changed the software’s dependencies.

If anything refuses at this stage, stop. Nothing has been changed, so there is no urgency and no risk in stopping. Skip to section 9.

7. Install

The same command, without --dry-run:

bash install.sh --trust-fingerprint PASTE-FINGERPRINT-HERE

Quicker: press the Up arrow to bring back the command you just ran — fingerprint already filled in — then delete the --dry-run from it and press Enter. This avoids pasting the fingerprint a second time, which is where a typo would otherwise creep in.

While this runs: do not power off the instrument, close the terminal, or remove the USB stick. The instrument restarts its own software partway through, so a pause of a couple of minutes is normal and does not mean it has hung.

On a device that has already taken one offline update, --trust-fingerprint is no longer needed. The instrument remembers the key from the first time, and its own memory always wins over anything in a package.

8. What the last line means

Only the last row is serious, and it is rare. Everything else either worked or left the instrument exactly as it was.

9. If something goes wrong

Common refusals, and what they mean

Always send the log

The installer writes a full record back onto the USB stick:

airgap-install-TIMESTAMP.log

Copy that file off the stick and email it to support@skopii.com. For an instrument with no network connection, that file is the entire diagnostic record — there is no telemetry, no remote access, and nothing else for us to look at. Please send it even when you are not sure anything went wrong.

The universal repair: reconnect it to a network

If an instrument ends up in any doubtful state after an offline update, and you are able to get it onto a network even temporarily, this restores it:

ping -c1 github.com
bash ~/.artimis/devices/artimis/scripts/artimis_update.sh sync production

Use staging instead of production if that is the channel the instrument follows — the Channel: line in step 6 tells you which.

Use sync, not apply. apply checks whether the version is current and stops if it is — so if the software is in place but its dependencies are half-installed, apply will report “nothing to do” and fix nothing. sync rebuilds everything from scratch whether it looks current or not. It is the repair command.

An offline update cannot damage the instrument’s ability to recover this way: it never changes where the instrument looks for updates, and the updater program itself is restored from the software repository on every activation.

10. Confirm it worked

• Open the instrument’s web interface and check the About / Software card shows the new version.
• Start the live preview and confirm a real image appears in both brightfield and darkfield.
• Run one short sample end to end, and confirm particles are both detected and classified. A run that detects particles but classifies nothing can indicate an incomplete update — tell us if you see it.

Still stuck?

Email support@skopii.com with the airgap-install-TIMESTAMP.log file from the USB stick. There is no telemetry on an offline instrument, so that file is the only thing we can work from — send it even if you are unsure anything went wrong.