signalk-fcm-notify

A Signal K server plugin that forwards your boat's notifications (alarms and alerts) to Firebase Cloud Messaging (FCM) as push messages. Subscribed phones, tablets, or apps get the alert even when closed and off the boat's network.

Messages go to an FCM topic, so every device subscribed to that topic is notified at once — no per-device registration. Any FCM-capable client can receive them.

Requirements

• A running Signal K server.
• A free Google Firebase project (delivers the push).
• One or more apps/devices that receive FCM and subscribe to your topic.

Install

In the Signal K admin UI: Appstore → Available, search for signalk-fcm-notify, install, and restart the server. (To install from source instead, see DEPLOY.md.)

Firebase setup

1. In the Firebase console, create or open a project.
2. Project settings → Service accounts → Generate new private key. A .json file downloads — this is your service-account key. Keep it secret.
3. In the Google Cloud console, ensure Cloud Messaging API (V1) is enabled for the project.
4. Copy the key onto the Signal K machine and lock it down:

   chmod 600 /home/pi/.signalk/fcm-service-account.json

   Any location works — note the full path for the next step.

Configure

In the admin UI: Server → Plugin Config → FCM Notify. Enable it, then set the service-account key path and project id, and Submit.

| Setting | Required | Default | Purpose | |---|---|---|---| | Firebase service-account key path | ✅ | — | Full path to the service-account .json on the server. | | Firebase project id | ✅ | signalk-android-app | Must match your Firebase project and key. | | FCM topic | | boat-notifications | Topic messages are sent to; every receiver subscribes to this. | | Push normal/clear transitions | | on | Also push when an alarm clears, so clients can dismiss it. | | App google-services.json path | | — | Optional; enables auto-discovery. | | Debug logging | | off | Extra detail in the Signal K log. |

Trigger any Signal K notification and confirm a push arrives on a subscribed device.

What gets sent

For each notification the plugin sends an FCM data message (not a notification message), so clients can render it freely even when backgrounded:

| Key | Meaning | |---|---| | title | Short heading | | message | Alert text | | path | Signal K path it came from (also used to de-duplicate) | | state | emergency, alarm, alert, warn, or normal |

Notifications re-fire constantly, so a push is only sent when a path's state or message actually changes — no duplicate spam.

Optional: app auto-discovery

Lets a client read the non-secret connection settings from your server and configure itself in one tap, instead of entering them by hand on each device.

1. Download your Firebase Android app's google-services.json (Firebase console → Project settings → Your apps → Android app).
2. Copy it onto the server (a separate file from the service-account key), e.g. /home/pi/.signalk/google-services.json.
3. Set App google-services.json path to its full path and Submit.

Only non-secret client values are served (at GET /signalk/v1/api/fcm-notify/client-config, readable with a normal read/device token). The service-account key is never exposed. Leave the path empty to keep auto-discovery off.

Troubleshooting

• No push arrives. Turn on Debug logging, then watch sudo journalctl -u signalk -f. Check the plugin's status line shows it forwarding and that your device subscribes to the same topic.
• Plugin won't start. Verify the service-account key path is absolute and readable by the Signal K user, and that Firebase project id matches the key.
• Auto-discovery not offered. Confirm App google-services.json path is set and the plugin restarted; its status line mentions auto-discovery when the file loaded.

Develop

npm install
npm run build
npm test

Deployment options: DEPLOY.md.

Note

Parts of this plugin were written with AI assistance. Reviewed and tested before release; issues and PRs welcome.