Skip to content
vxnsinPublic

About

Self-hosted, open-source location sharing: a React Native app plus a lightweight Node.js WebSocket server that shows all your devices on one map.

Topics

Resources

Stars

2 stars

Watchers

0 watching

Forks

Repository files navigation

NeoPin

Location sharing for family and friends, on a server you run yourself.

Platform Expo SDK React Native App version Server License

Server · Quick start · How it works · Build · Push · Server docs


NeoPin dashboard: six people on a map of Berlin, with the people panel showing devices, battery and groups

NeoPin shows where your people are, like Find My or Google's location sharing, except that the positions go to a small server of your own and nowhere else. Everyone gets an account, groups decide who sees whom, and the phones and the web dashboard all draw the same live map.

The app is the phone half. It reports where you are, in the background too, and shows everyone you share a group with as a round picture or their initials: green while they report, yellow when the last position is getting old, grey when they are offline, with the battery next to each device. Tap someone to ask their phone for a fresh fix, or ask to find them. Once they say yes, you both see each other move live for half an hour, with an arrow on the lock screen and Bluetooth telling you when the last few metres are left.

How it works

flowchart LR
    A[📱 NeoPin app] <-- "WebSocket · token" --> S[(🖥️ NeoPin Server<br/>Node.js · SQLite)]
    B[📱 NeoPin app] <-- "WebSocket · token" --> S
    S <-- "WebSocket · session" --> D[🌐 Web dashboard]
    S -. "wake-ups, notifications (optional)" .-> F[Firebase Cloud Messaging]
    F -.-> A
Loading

The app signs in once with a username and password and gets a device token. From then on it keeps a WebSocket open and sends its position whenever it moves; fixes taken without a connection follow later in one batch, so the history has no holes. The server keeps the live map in memory, stores the history in SQLite and pushes every change to the phones and dashboards that may see it.

On Android a foreground service keeps reporting while the app is closed, on iOS the system wakes a background location task on movement. How often is up to you: Battery saver (every 2 minutes or 100 m), Balanced (15 s or 10 m) or Precise. Maps are vector tiles from OpenFreeMap on MapLibre, light or dark with the system. The 3D switch adds mountains and buildings; the terrain comes from the AWS Open Data Terrain Tiles (Mapzen, SRTM and others).

Your days, afterwards

The timeline of one day: stays at home, the studio and a café, with walks and bike rides between them on the map

From the stored positions the server builds a timeline, much like Google's: where you stayed and how you got from one place to the next, on foot, by bike, by car, or by bus, tram and train where timetable data covers your area. Name a place once and it is recognised from then on; a stop that was none can be dismissed and a wrong mode corrected. Your timeline is private until you share it with a group or with chosen people. Your places can also tell others when you arrive or leave.

The weekly review: distance, time on the move, trips and stops, a map of the week, kilometres per day and how you got around

Every Monday, and on the first of a month, the review adds it up: kilometres, time on the move, the places you spent the most time at and the lines you rode most.

Note

Positions stay on your server. Place names, timetables and smoother paths come from public services (Overpass, Photon, GTFS feeds, OSRM) that each see only what they need, and each of them can be pointed at your own instance or switched off. The server configuration says what each one sees.

Repository layout

The app and the server live in the same repository on different branches.

Branch / tag Contents
main The React Native / Expo app. You are here.
Server Node.js server with the web dashboard and its own README. Server releases are tagged there and published as a Docker image.
archive/flutter (tag) The original Flutter app before the React Native rewrite.

Quick start

1. Run the server

The quickest way is the Docker image:

docker run -d --name neopin -p 3012:3012 -v neopin-data:/app/data --restart unless-stopped \
  ghcr.io/vxnsin/neopin-server:latest
docker logs neopin

The first start creates the admin account and prints its generated password once in the log. Open http://<your-ip>:3012, log in, and a short setup asks for your own password and a first group. Node without Docker, Compose, HTTPS and every setting are in the server README.

2. Run the app

git clone https://github.com/vxnsin/NeoPin.git
cd NeoPin
npm install
npx expo run:android   # or: npx expo run:ios

The app has native parts (background location, push, the lock screen view and Bluetooth during a find), so Expo Go won't do: you need a development build.

3. Sign in

Enter the server address (192.168.1.20:3012 at home, neopin.example.com behind HTTPS) and the username and password the admin made for you. Or sign up with an invite code: anyone on the server can create one in the app or the dashboard, and the invite link opens the app with the code and the server already filled in.

Allow location access “all the time”, otherwise reporting stops as soon as the screen locks. A short tour shows the controls on the first start.

Warning

Plain ws:// is fine at home. Over the internet, put the server behind HTTPS and connect with its host name, otherwise passwords, tokens and every position travel unencrypted.

Build the app

Builds are configured in eas.json.

Profile Command Output
development eas build --profile development Dev client for local testing
preview eas build --profile preview --platform android Installable APK
production eas build --profile production Store build, the build number goes up by itself

JavaScript changes reach installed apps with EAS Update, no new build needed. Native changes (a new module, a permission, Firebase) need a new build.

Diagnostics in preview builds

Builds on the preview channel (and development) keep a small log on the phone and show a Developer section in the settings. Export diagnostics packs it into a zip, uploads it to your own server and opens the share sheet with a link that works for 7 days, ready to paste into a chat. Clear log starts it over. Store builds keep no log and show no section.

The zip holds summary.json (device model and OS, app, update and runtime version, preset, permissions, battery drain per hour, fixes per hour by source, duplicate rate, reconnects), events.jsonl (every logged event), errors.txt and settings.json. The log keeps at most 2000 events or 512 KB.

It never holds a position: a fix is logged with its accuracy, speed, age and the distance to the previous fix, never its coordinates. Keys like token, password, latitude or serverIp are dropped, and error texts are scrubbed of bearer tokens, long ids and coordinate pairs. The only account detail in it is the username. The server side, including DIAGNOSTICS=off, is in the server README.

Push notifications (Android)

Push uses Firebase Cloud Messaging. It wakes a phone without a connection when someone asks for its position or wants to find that person, and it delivers group invitations, arrival alerts, ride questions and the review. Without the Firebase config the app builds and runs as before, it just gets no push.

  1. Create a project in the Firebase console and add an Android app with the package name de.vensin.neopin.
  2. Download google-services.json and either put it into the app/ folder (it stays out of git, .easignore does not exclude it so EAS Build uploads it), or store it as an EAS file secret named GOOGLE_SERVICES_JSON.
  3. Give the server the service account key of the same project (server docs), it sends the messages.
  4. Build a new APK. Push needs the native Firebase setup, an EAS Update alone is not enough.

The server has to report push: true in GET /api/status, otherwise the app does not send its token.

Reference

Protocol

The app gets its token from POST /api/auth/login ({ username, password, deviceId, deviceType }), then opens a WebSocket and sends JSON. The full protocol and every HTTP route are in the server README.

App → Server Purpose
{ "type": "authenticate", "deviceId", "token", "deviceType"? } Log in. The server answers { "successful": true, "features": [...] } or closes with code 4000
{ "type": "updatePosition", "latitude", "longitude", "battery"? } The own position, with the battery as { level, charging }
{ "type": "positionBatch", "points": [...] } Up to 100 fixes taken while there was no connection, each with recordedAt
{ "type": "updateBattery", "level", "charging" } Only the battery changed
{ "type": "pingDevices" } Ask every other visible device for a fresh position
{ "type": "findRequest" | "findAnswer" | "findPosition" | "findEnd", ... } Ask to find someone, answer, share the live position, stop
{ "type": "ping" } Keep-alive, answered with pong
Server → App Purpose
{ "type": "dataResponse", "devices": [...] } Every device you may see, pushed on every change
{ "type": "requestLocation" } Send an updatePosition now
{ "type": "findRequest" | "findPending" | "findStarted" | "findPosition" | "findEnded", ... } The other side of a find
{ "type": "rideQuestion", "rideId", "transit", "at" } “Are you on this line?”, answered over HTTP
{ "type": "notificationsChanged" } New notifications to fetch
App structure
app/
├─ _layout.tsx        socket provider, position reporting, background service
├─ index.tsx          start screen, then auto-connect
├─ login.tsx          server address, sign-in, sign-up with an invite code
├─ invite.tsx         opened by invite links
├─ map.tsx            map, people sheet, settings, timeline, find
└─ review.tsx         weekly and monthly review
components/           sheets and panels: timeline, groups, alerts, find, tour, ...
lib/
├─ SocketClient.ts    reconnecting WebSocket client with heartbeat and queue
├─ socket.ts          the one shared client and the stored credentials
├─ api.ts             HTTP calls with the device token
├─ mapHtml.ts         the MapLibre page inside the WebView
├─ timeline.ts        stays and trips as the timeline shows them
├─ find.ts            find sessions, nearby.ts for their Bluetooth part
├─ fixes.ts           GPS fixes with their own time, for late batches
└─ ...                push, groups, invites, review, settings
modules/
├─ neopin-live/       lock screen view during a find (Android notification, iOS Live Activity)
└─ neopin-nearby/     Bluetooth proximity during a find
tasks/                background location and push tasks
handlers/, hooks/     server messages, location reporting, theme, permissions
themes/               light and dark palettes
__tests__/            Jest tests

npm test runs the Jest tests: the socket client (login, reconnect, queue, heartbeat) against a fake WebSocket, and the logic behind the timeline, find, review, push payloads, invites and the rest.

License

MIT


Made by Vensin · vensin.dev

About

Self-hosted, open-source location sharing: a React Native app plus a lightweight Node.js WebSocket server that shows all your devices on one map.

Topics

Resources

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages