kaaka docs

Getting started

You need one Android phone (Android 10 or newer) with a SIM that can send SMS, and a laptop on the same Wi-Fi. The phone becomes the Kaaka number.

1. Start the control room

git clone https://github.com/twilighty-abhi/kaaka
cd kaaka
python3 -m venv .venv-mac && .venv-mac/bin/pip install -r server/requirements.txt
.venv-mac/bin/python server/server.py

The banner prints the laptop's Wi-Fi address and a network name. Open http://kaaka.local:8080/admin (or http://<ip>:8080/admin) in a browser, or use the Open control room button on the landing page: that is the control room. With a token or demo PIN set, it asks for it first. http://<ip>:8080/ is the public landing page and /docs is this wiki.

Before anyone else can reach it, set a token. export KAAKA_ADMIN_TOKEN=<long random string> before starting the server, then open the control room once as /admin?token=<the token>. Without a token anyone on the network can read callers' numbers and locations. See Running in production.
kaaka.local is announced on the local network over mDNS (Bonjour), so it keeps working when the laptop's IP changes. Laptops, iPhones and most desktops open it directly; Android depends on the version. In Kaaka Call, use the IP address.

2. Install Kaaka Call on the Kaaka number

  1. Copy gateway/Kaaka.apk to the phone and install it. On a phone that had an earlier debug build, uninstall that first.
  2. Open Kaaka Call. The setup card lists four rows. Make each one green:
    • call screening: tap [enable] and choose Kaaka Call as the caller ID & spam app.
    • sms send / receive: tap [allow].
    • calls from contacts: tap [allow] (phone, call log and call management). Android does not pass calls from saved contacts to call screening, so Kaaka Call handles them another way.
    • battery optimisation: tap [exempt] so the phone never puts Kaaka to sleep.
  3. Tap [config] and fill in:
    • responder numbers: the phones that should be texted on every call, comma or newline separated.
    • dashboard server: http://<laptop ip>:8080.
    • dashboard token: the same value as KAAKA_ADMIN_TOKEN, if you set one.
    Leave the rest at the defaults for now and tap save. Saving sends a heartbeat; within a minute the control room header shows the phone as seen.

The header reads active when screening and SMS are both on. Settings are stored natively, so Kaaka keeps working with the app closed and the screen locked.

3. Make a test call

  1. From another phone, call the Kaaka number. It should be rejected within a second.
  2. That phone receives the reply SMS. Each responder receives the call alert.
  3. The control room's live page shows a new open incident.
  4. From a responder phone, text ACK to the Kaaka number. The caller gets a confirmation and the incident shows "acknowledged".
  5. Text RESOLVE from the responder phone. The incident moves to history.

The full checklist with every feature is in docs/TESTING.md in the repository.

4. Register responders in the control room

On the responders page add each responder with a name, phone number and home position (type lat, lon or use [pick on map]). This is what makes the nearest-responder dispatch work; the responder numbers in Kaaka Call are what get the SMS. Use the same numbers in both places. See Responders.

5. Optional: Kaaka Sensors for callers

People who want an SOS button and automatic location reports install client/KaakaSensors.apk on their own phone and enter the Kaaka number in its settings. See Kaaka Sensors. The Kaaka number itself does not need it.

Kaaka 1.0.0 · Edit this page · In immediate danger, call 112.