bench get-app https://github.com/DonnC/fcm

[![Listed on Frappe Gems](https://frappegems.com/api/method/frappe_gems.seo.badge?app=DonnC%2Ffcm)](https://frappegems.com/gems/apps/DonnC/fcm)

Frappe Cloud Messaging

Frappe Cloud Messaging is a standalone, topic-first messaging layer for Frappe apps and managed Android devices, powered by MQTT.

It is designed for controlled device fleets such as POS terminals, kiosks, and internal business apps where the operator has more control than a consumer Android ecosystem. The goal is to give Frappe a Firebase-like command channel without pretending to be Firebase.

What It Does

• Registers devices with Frappe.
• Stores device metadata and the last known subscribed topics.
• Publishes commands to concrete MQTT topics.
• Receives device-originated events on a controlled uplink namespace.
• Keeps the backend and SDK in sync through a reserved device sync topic.
• Lets the Android SDK hide the MQTT details from the host app.

Core Design

FCM follows a very simple rule set:

1. MQTT is the live transport.
2. REST is for setup and administration.
3. Topics are the routing model.
4. The backend does not need to understand group concepts as first-class objects.
5. The SDK reports its state back to the backend on a reserved sync topic.

Reserved topic model

• Downlink commands: /fcm/d/{device_id} or any agreed concrete topic.
• Uplink events: /fcm/u/{device_id}/....
• Device sync: /fcm/s/{device_id}/sync.

The backend listens on /fcm/u/# and /fcm/s/# so it can capture events and topic-state updates.

Project Docs

The design notes live in docs/:

• Managed device overview
• Managed device deep dive
• Backend contract
• Android SDK contract

If you are extending the project, those documents are the source of truth for the current direction.

Current Backend Shape

The backend is intentionally small.

Suggested DocTypes

• FCM Settings
• FCM Device
• FCM Device Subscription
• FCM Topic
• FCM Outbound Message
• FCM Inbound Message optional
• FCM Delivery Log optional

Backend helpers already present

• Device registration and refresh helpers.
• Topic sync helpers.
• MQTT publish worker logic.
• Inbound listener scaffolding.
• Reserved sync topic handling.

Android SDK Shape

The Android SDK is intended to be a small dependency that an existing POS app can drop in with minimal setup.

Core SDK surface

• init(...)
• connect()
• disconnect()
• subscribe(topic)
• unsubscribe(topic)
• publish(topic, payload)
• setListener(...)

SDK behavior

• Restores local state after restart.
• Reconnects automatically.
• Resubscribes to saved topics.
• Emits the device sync payload when subscriptions change.
• Forwards all received messages to the host app through one callback.

Typical Flow

sequenceDiagram
    participant App as Android App
    participant SDK as FCM SDK
    participant Broker as MQTT Broker
    participant Frappe as Frappe Backend

    App->>SDK: init()
    SDK->>Frappe: register device
    Frappe-->>SDK: device record + topics + broker config
    SDK->>Broker: connect and subscribe
    SDK->>Broker: publish sync payload to /fcm/s/{device_id}/sync
    Broker->>Frappe: deliver sync payload
    Frappe->>Frappe: update subscribed_topics
    Frappe-->>SDK: publish command to concrete topic
    Broker-->>SDK: deliver message
    SDK-->>App: onMessageReceived(...)

Broker Support

The app defaults to a self-hosted Mosquitto-style setup, but the broker is configurable.

The backend settings should support:

• Broker URL
• Broker port
• SSL/TLS
• Username/password
• Client ID
• Keepalive
• Inbound topic filter

Development Status

This project is under active design and implementation.

Right now the focus is on:

• Backend MQTT plumbing.
• Device registration and topic sync.
• Lean Android SDK contracts.
• Clear docs before expanding the data model.

Installation

Install this app into a Frappe bench environment:

cd $PATH_TO_YOUR_BENCH
bench get-app $URL_OF_THIS_REPO --branch develop
bench install-app fcm

If you are developing locally inside a bench, the app depends on paho-mqtt:

• paho-mqtt>=2.1.0,<3

Contributing

This repository uses pre-commit for code formatting and linting.

cd apps/fcm
pre-commit install

Configured tools:

• ruff
• eslint
• prettier
• pyupgrade

License

MIT