Quick Start

B-Sense Quick Start

Get from unpacked board to first live glucose reading with the fewest possible steps.

Use this guide if you want the shortest practical path to a working B-Sense display.

Documentation Menu

Before You Start

You will need:

  • a compatible ESP32 2.8 inch touch display board using ST7789
  • a USB cable for flashing
  • Wi-Fi details for the network the device will use
  • one data path only for the first setup:

– your existing Nightscout setup – or a B-Sense Cloud access path

Keep the first setup simple:

  • choose one data path, not both
  • flash the latest firmware first
  • confirm one live reading before changing layouts or extra settings

Choose Your Path

Phone Compatibility Rule Right Now

Current working rule:

  • if your phone can run xDrip+, your setup is the most likely to be compatible with the current B-Sense path
  • Apple / iPhone compatibility is not yet treated as tested in the current baseline

For now, treat:

  • Android + xDrip+ path as the primary supported direction
  • Apple / iPhone path as not yet confirmed until it is explicitly tested and recorded

Option A: Nightscout path

Use this if:

  • you already have Nightscout working
  • you want to keep your current data flow

What you need ready:

  • your Nightscout URL
  • your Nightscout upload credential: API_SECRET or a write-capable token

Important:

  • in xDrip+, the setup screens are the same for both Nightscout and B-Sense Cloud
  • only the server URL and the matching secret/key change
  • do not use a readable Nightscout token for xDrip+ upload
  • if you later want a locked-down read-only browser/follower link for Nightscout, create that as a separate readable token in Nightscout Admin Tools

Option B: B-Sense Cloud path

Use this if:

  • you want a lighter hosted setup path
  • you do not want to manage your own Nightscout instance for the first setup

What you need ready:

  • the B-Sense Account Setup page and the access details shown there
  • the access details used by your current B-Sense cloud option

Use the current B-Sense Account Setup page as the source of truth for the values you should enter.

If you configure xDrip+ Cloud Upload for B-Sense Cloud, the Base API URL follows this format:

  • https://YOUR_BSENSE_API_KEY@api-b-sense.hismis.com/api/v1/

This is the same xDrip+ Nightscout Sync screen flow as Nightscout. Only the URL and the matching auth value change.

Step 1: Open The Web Flasher

Open:

Then:

  1. Connect the device over USB.
  2. Click Connect.
  3. Select your device/serial port.
  4. Choose the latest firmware.
  5. Install B-Sense ESP32 + ST7789.

For the first install, erase is usually the safest option.

What you should see next:

  • the board appears as a selectable serial device
  • the flash finishes without leaving the page in a stuck loading state
  • the board restarts after install

Step 2: Connect The Device To Wi-Fi

After flashing:

  1. Set the Wi-Fi network.
  2. Wait until the device reports that it connected.
  3. Open Visit Device if the flasher offers it.

At this point the device should be online on your local network.

If the flasher does not offer a direct link, the next setup step still happens on the device’s local web page. Open the device by its local IP or the device page link shown by the flasher.

What you should see next:

  • the device reports a successful Wi-Fi connection
  • the local setup page opens
  • the local setup page shows the main tabs for Connection, Settings, Pro Features, and Status

Step 3: Enter Your Data Source Settings

Use the local device web page:

  • Connection tab:

– Wi-Fi – host / URL – token / API key / secret

  • Settings tab:

– glucose unit – time zone

  • Pro Features tab:

– layout – brightness schedule – glucose range thresholds – advanced display tuning after the base setup already works

  • Status tab:

– firmware version – update check – restart / reset actions

If you use Nightscout

Enter:

  • Nightscout host / URL
  • Nightscout upload credential: API_SECRET or a write-capable token

Do not mix auth roles:

  • readable token = read-only follower/browser access
  • uploader credential = for xDrip+ sending data into Nightscout

If you use B-Sense Cloud

Enter:

  • the B-Sense host / URL shown for your current path
  • your B-Sense Cloud API key or access secret, depending on the current flow

For the xDrip+ Nightscout Sync screen, the practical Base API URL format is:

  • https://YOUR_BSENSE_API_KEY@api-b-sense.hismis.com/api/v1/

Keep credentials exact:

  • no extra spaces
  • no missing https://
  • no mixed Nightscout and B-Sense Cloud values in the same setup

Do not start by changing layout or brightness first. Save the data path, wait for the first live reading, and only then continue with cosmetic or advanced settings.

What you should see next:

  • the device accepts the saved connection values
  • after save, the device starts trying to fetch glucose data
  • if the local setup page has status information, it should reflect the saved path instead of an empty setup state

Step 4: Wait For The First Reading

After saving the settings:

  1. Give the device up to a few minutes for the first fetch.
  2. Confirm the glucose value appears.
  3. Confirm the trend arrow appears.
  4. Confirm the value updates again on the next normal refresh.

Target outcome:

  • one live glucose value
  • one visible trend state
  • normal refresh continues without manual retry

Typical first-success signs:

  • the device stops showing only a setup/empty state
  • the glucose value appears in the selected unit
  • the trend arrow becomes visible
  • the next refresh still arrives without re-entering settings

If the first reading appears but the second one never arrives, do not keep changing settings. Treat that as a diagnostics case and move to:

Fast Checks If No Data Appears

If you still do not see a reading after about 3 minutes:

  1. Recheck Wi-Fi on the device.
  2. Recheck the host / URL.
  3. Recheck the token / secret / API key.
  4. Confirm you selected only one data path.
  5. Restart the device once and test again.

If you cannot even reopen the local device setup page:

  1. confirm the board is still on Wi-Fi
  2. reconnect from the flasher if it offers Visit Device
  3. restart the board once and reopen the local device page

Before changing multiple settings at once, note:

  • which path you selected
  • which host you entered
  • whether the board ever showed one live reading
  • whether the local setup page is still reachable

If The Device Shows Stale Or Offline Data

Check these first:

  • your phone/app/cloud path is still updating upstream
  • the device still has Wi-Fi
  • the configured host is reachable
  • the saved credentials match the intended path

If the device worked before and stopped later, restart once first. If the problem repeats, capture:

  • the last successful fetch time
  • the current Wi-Fi state
  • the current configured data path
  • whether the device still shows the last value or dropped back to an empty state

After The First Successful Reading

Once the first reading is stable, you can continue with:

  • screen layout changes
  • glucose unit selection (mmol/L or mg/dL)
  • night mode / brightness settings
  • OTA update checks

The best next page after first success is:

Those changes are easier after the core data path already works.

Recommended order after first success:

  1. confirm the glucose unit
  2. confirm the time zone
  3. choose the layout you prefer
  4. adjust night mode and brightness if needed
  5. check OTA only after the device has already been stable for a while

Related Pages

Screenshot Coverage

The firmware screenshot workflow already captures:

  • main UI layouts
  • no-data and stale states
  • mini menu screens
  • both glucose units

Source:

  • docs/firmware-doc-screenshot-workflow.md
  • docs/assets/firmware-doc-screenshots/