Technician handover · GSM and keypad protocol v1.0
Secure water-credit message specification.
Use these templates to configure the H-TECH PLC GSM workflow. Replace placeholders on the server. Never send or expose a real meter secret, password, M-Pesa credential or customer data in this document.
Mandatory rule
Cash → command → acknowledgement
Never accept plain messages such as “ADD 20 LITRES” or “START”. Reject wrong meter numbers, invalid signatures, expired commands and duplicates. On low tank, sensor fault, emergency stop, power restart or GSM failure, keep the valve closed.
1. M-PesaPayment confirmed.
2. SMSServer sends signed TOPUP.
3. EEPROMPLC saves credit once.
4. ACKPLC reports outcome.
Server → PLC
Paid water-credit command
HTW1|TOPUP|<METER_NO>|<COMMAND_ID>|<CREDIT_ML>|<AUTO_START>|<EXPIRY_UTC>|<SIG16>
| Field | Requirement |
|---|---|
| HTW1 | Protocol version. |
| TOPUP | Adds credit cumulatively. Never overwrite existing balance. |
| METER_NO | Must match meter number saved in PLC EEPROM. |
| COMMAND_ID | Unique command. Save recent applied IDs in EEPROM. |
| CREDIT_ML | Positive integer millilitres only. |
| AUTO_START | 1 may open valve only if local safety checks pass. 0 stores credit only. |
| EXPIRY_UTC | UTC format: YYYYMMDDTHHMMSSZ. |
| SIG16 | First 16 uppercase hexadecimal characters of HMAC-SHA256. |
Canonical text and signature
HTW1|TOPUP|<METER_NO>|<COMMAND_ID>|<CREDIT_ML>|<AUTO_START>|<EXPIRY_UTC>
SIG16 = first 16 uppercase hexadecimal characters of
HMAC-SHA256(METER_SECRET, canonical_text)
Use a different METER_SECRET for each physical meter. Store it in protected PLC EEPROM and secure server configuration only.
Illustrative sample — not a real signature
HTW1|TOPUP|HWM-APT-A01|CMD8F31C2|25000|1|20260816T230000Z|<SIG16>
PLC → server
Acknowledgement command
HTW1|ACK|<METER_NO>|<COMMAND_ID>|<STATE>|<CREDIT_ML>|<BALANCE_ML>|<VALVE>|<SIG16>
Allowed states: APPLIED, APPLIED_SAFE_STOP, REJECTED_BAD_SIGNATURE, REJECTED_EXPIRED, REJECTED_DUPLICATE, REJECTED_WRONG_METER, REJECTED_FAULT. Valve is OPEN or CLOSED.
HTW1|ACK|HWM-APT-A01|CMD8F31C2|APPLIED|25000|185500|OPEN|<SIG16>
Emergency action
Remote safe stop
HTW1|STOP|<METER_NO>|<COMMAND_ID>|<REASON>|<EXPIRY_UTC>|<SIG16>
On a valid STOP, close the valve and stop the pump immediately. Keep stored water credit unchanged, log the event and return ACK.
Manual recovery
Keypad token flow
Do not release water just because a token was typed. The PLC must ask the central server to validate the one-time token, then apply the signed TOPUP response once.
HTW1|TOKEN|<METER_NO>|<TOKEN>|<NONCE>
- PLC sends TOKEN request through GSM.
- Server checks meter binding, expiry and unused token state.
- Server responds with signed HTW1|TOPUP command.
- PLC stores it once and returns ACK.
- Server marks token used only after ACK.
Customer SMS template
H-TECH PREPAID WATER METER
Meter: <METER_NO>
Payment received: KSh <AMOUNT>
Water credit: <LITRES> L
Manual token: <TOKEN>
Token expires: <EXPIRY_LOCAL>
Enter token on the meter keypad if automatic credit is delayed.
Commissioning checklist
Required PLC behaviour
- Persist meter number, individual secret, balance, recent command IDs and fault state in EEPROM.
- Use an EEPROM journal/checksum so power loss cannot double-credit water.
- Verify HMAC before changing balance or valve state.
- Reject duplicate commands after power restart.
- Test low tank, no-flow, sensor fault, emergency stop and GSM failure with valve closed.
- Send customer “credit applied” notification only after the PLC ACK.