Skip to content

Device Parameter Configuration Documentation

Overview

This document outlines the process for configuring parameters on a device (e.g., a VCUA device) via MQTT. The configuration includes setting the Access Point Name (APN), upload frequency (GPRS Sleep Time Window), Fleet ID (FLID), and recharging the device using a public key or recharge code. Each task involves publishing a command to a specific MQTT topic, with the device responding via a status payload. The instructions assume the use of an MQTT client (e.g., MQTT Explorer) and a device with an ID such as VCUA2404000000.

The sample payload provided is a JSON object returned by the device, containing five main sections: att (attributes), cmd (commands), sts (status), dta (data), and dia (diagnostics). Each section includes key-value pairs where keys are acronyms, and this documentation expands them into full descriptions for clarity.

Configuration Tasks

1. Configure APN Settings

Purpose: Sets the Access Point Name (APN) for the device’s GPRS connection to connect to the carrier’s network.

Steps:

  1. Log in to MQTT Client: Open your MQTT client (e.g., MQTT Explorer) and connect to the broker.
  2. Publish Command:
    • Topic: cmd/V01/GPRSV2//VCUA/[DEVICE_ID]
      • Replace [DEVICE_ID] with the actual device ID (e.g., VCUA2404000000).

    • Payload:

      json

      CollapseWrapCopy

      { "set": { "apn": "[APN_NAME]" } }

      • Replace [APN_NAME] with your carrier’s APN (e.g., orange.m2m.spec).

Example:

  • Topic: cmd/V01/GPRSV2//VCUA/VCUA2404000000

  • Payload:

    json

    CollapseWrapCopy

    { "set": { "apn": "orange.m2m.spec" } }

Confirmation: The device responds with a status payload (see "Sample Device Payload" section) where the cmd.napn field reflects the updated APN (e.g., "orange.m2m.spec").

2. Set Upload Frequency

Purpose: Configures the GPRS Sleep Time Window (gstw), which determines how often the device uploads data (in minutes). The minimum value is 6 minutes.

Steps:

  1. Publish Command:
    • Topic: cmd/V01/GPRSV2//VCUA/[DEVICE_ID]

    • Payload:

      json

      CollapseWrapCopy

      { "set": { "gstw": 60 } }

      • The value (60) represents 60 minutes. Adjust as needed, ensuring it’s greater than 6.

Example:

  • Topic: cmd/V01/GPRSV2//VCUA/VCUA2404000000

  • Payload:

    json

    CollapseWrapCopy

    { "set": { "gstw": 60 } }

Confirmation: The device updates cmd.gstw in the status payload (e.g., 60), confirming the new upload frequency.

3. Set FLID ID

Purpose: Assigns a custom Fleet ID (flid) to the device for identification within a group or fleet.

Steps:

  1. Publish Command:
    • Topic: cmd/V01/GPRSV2/fleet/VCUA/[DEVICE_ID]

    • Payload:

      json

      CollapseWrapCopy

      { "set": { "flid": ["CUSTOM_VALUE"] } }

      • Replace CUSTOM_VALUE with your desired identifier (e.g., "willing"). Note that flid is an array.

Example:

  • Topic: cmd/V01/GPRSV2//VCUA/VCUA2404000000

  • Payload:

    json

    CollapseWrapCopy

    { "set": { "flid": ["willing"] } }

Confirmation: The device updates att.flid in the status payload (e.g., "willing" instead of an empty string).

4. Recharge the Device

Purpose: Recharges the device’s PAYG (Pay-As-You-Go) credit using a recharge code, extending its operational days.

Steps:

  1. Publish Command:
    • Topic: cmd/V01/GPRSV2//VCUA/[DEVICE_ID]

    • Payload:

      json

      CollapseWrapCopy

      { "set": { "pubk": "[RECHARGE_CODE]" } }

      • Replace [RECHARGE_CODE] with the recharge code (e.g., *015 596 899 441 605 616 031#).

Example:

  • Topic: cmd/V01/GPRSV2//VCUA/VCUA2404000000

  • Payload:

    json

    CollapseWrapCopy

    { "set": { "pubk": "*015 596 899 441 605 616 031#" } }

Confirmation: The device updates cmd.pubk with the new code and adjusts sts.rcrd (Remaining Credit Days) in the status payload (e.g., from 1 to 11 days).

Sample Device Payload

The device responds to configuration commands or status requests with a JSON payload. Below is a sample payload with explanations:

json

CollapseWrapCopy

{
  "att": {
    "opid": "VCUA2404000000",
    "ppid": "VCUA2404000000<<<<<<",
    "flid": "",
    "ccid": "89330123607808970780",
    "frmv": "4.0.6"
  },
  "cmd": {
    "pubk": "*015 596 899 441 605 616 031#",
    "gstw": 60,
    "gctw": 59,
    "napn": "orange.m2m.spec",
    "swch": 0,
    "read": 0,
    "rptm": 0,
    "raml": [],
    "hbfq": 1
  },
  "sts": {
    "sstc": 0,
    "crtm": "",
    "udtm": "",
    "time": "",
    "plat": 0.00,
    "plon": 0.00,
    "gpss": 28,
    "gpfc": 0,
    "rcrd": 0,
    "trhd": 0,
    "tpgd": 0,
    "pgst": 1,
    "tkre": 0,
    "ocst": 1
  },
  "dta": {
    "batp": 1991,
    "inpp": 1991,
    "outp": 0,
    "aeng": 1319,
    "pckv": 73400,
    "pckc": 27136,
    "rsoc": 81,
    "rcap": 24170,
    "fccp": 30530,
    "pckt": 0,
    "acyc": 43,
    "slon": 0.00,
    "slat": 0.00,
    "salt": 0,
    "sstm": " ",
    "sgps": 0,
    "sspe": 0,
    "ppst": 448,
    "pmcs": 0,
    "cmos": 1,
    "dmos": 1,
    "ctmp": 35,
    "mtpm": 0,
    "mtrd": 3218,
    "tspd": 31,
    "rvlt": 73,
    "rcur": -24036,
    "rmax": 0,
    "cmxs": 12000,
    "cmxc": 900
  },
  "dia": {
    "cv01": 3223,
    "cv02": 3229,
    "cv03": 3225,
    "cv04": 3224,
    "cv05": 3225,
    "cv06": 3228,
    "cv07": 3222,
    "cv08": 3229,
    "cv09": 3226,
    "cv10": 3226,
    "cv11": 3226,
    "cv12": 3224,
    "cv13": 3227,
    "cv14": 3224,
    "cv15": 3223,
    "cv16": 3228,
    "cv17": 3224,
    "cv18": 3217,
    "cv19": 3223,
    "cv20": 3223,
    "cv21": 3221,
    "cv22": 3220,
    "cv23": 3227,
    "pkt1": 30,
    "pkt2": 29,
    "pkt3": 29,
    "pkt4": 30,
    "pkt5": 32,
    "pkt6": 31
  }
}

Key Sections Explained

  • att (Attributes): Contains device identification and firmware details.
  • cmd (Commands): Reflects the current configuration settings and last commands sent.
  • sts (Status): Provides operational status and PAYG-related information.
  • dta (Data): Includes battery, power, and environmental data.
  • dia (Diagnostics): Reports cell voltages and temperatures for diagnostic purposes.

List of Acronyms with Full Meanings

Below is a comprehensive list of acronyms from the sample payload, with their full meanings as provided or inferred from context:

att (Attributes)

  1. opid: OEM Device ID. Factory set.
  2. ppid: PAYG Device ID. Factory set. Field override options.
  3. flid: Fleet ID. Factory set. Field override options.
  4. ccid: Cellular SIM Card ID (ICCID).
  5. frmv: Firmware Version. Factory set.

cmd (Commands)

  1. pubk: Public Key / Last Code
  2. gstw: GPRS Sleep Time Window in mins
  3. gctw: GPRS Connect Time Window in mins
  4. napn: GPRS Carrier APN Name
  5. swch: Generic device switch swch
  6. read: Last read request of ANY GATT = [opid|...|]
  7. rptm: Set notification request mode = [0|1|2|3|4], 0: Auto-Periodic | 1 = Request-Response | 2 = Change-Notification
  8. raml: Reserved AML (unknown context; possibly a list of reserved values)
  9. hbfq: Heart Beat Interval Minutes

sts (Status)

  1. sstc: System Status Code
  2. crtm: Created at time
  3. udtm: Update at time
  4. time: Device internal timer readout at last communication
  5. plat: Device GPS Latitude
  6. plon: Device GPS Longitude
  7. gpss: GPS Signal Strength in db
  8. gpfc: GPRS Connect Failure Counts
  9. rcrd: Remaining Credit Days
  10. trhd: Total Running History Days
  11. tpgd: PAYG Running Days
  12. pgst: PAYG State = PAYG | FREE
  13. tkre: Token response = NEW | REPEAT | ERROR
  14. ocst: Device Output State

dta (Data)

  1. batp: Battery Net Charging Power W
  2. inpp: Total Input Power W
  3. outp: Output Power W
  4. aeng: Accumulated Energy Output in Whs
  5. pckv: Pack Voltage mV
  6. pckc: Pack Current in mA
  7. rsoc: Relative State of Charge
  8. rcap: Remaining Capacity in Whs
  9. fccp: Full Charge Capacity in Whs
  10. pckt: Pack Temperature in Celsius
  11. acyc: Accumulated Cycles
  12. slon: Satellite Longitude in DD (decimal degrees)
  13. slat: Satellite Latitude in DD (decimal degrees)
  14. salt: Satellite Altitude in Metres
  15. sstm: Satellite-Synchronized Network Clock time in ISO 8601
  16. sgps: Satellite GPS Strength
  17. sspe: Satellite Speed in kM/h
  18. ppst: PACK protection status
  19. pmcs: Pack MOS Control Status (inferred; not explicitly defined)
  20. cmos: Discharging MOS Status, 0 for off, 1 for on
  21. dmos: Charging MOS Status, 0 for off, 1 for on
  22. ctmp: Controller Temperature in Celsius (inferred)
  23. mtpm: Maximum Temperature (inferred; possibly a typo for max temp)
  24. mtrd: Motor Running Distance (inferred; context unclear)
  25. tspd: Total Speed (inferred; possibly total operating speed)
  26. rvlt: Rated Voltage (inferred; possibly in volts)
  27. rcur: Rated Current (inferred; possibly in mA, negative indicates discharge)
  28. rmax: Rated Maximum (inferred; possibly max capacity or power)
  29. cmxs: Charge Maximum Voltage Setting (inferred; possibly in mV)
  30. cmxc: Charge Maximum Current Setting (inferred; possibly in mA)

dia (Diagnostics)

  1. cv01: Cell 01 Voltage mV
  2. cv02: Cell 02 Voltage mV
  3. cv03: Cell 03 Voltage mV
  4. cv04: Cell 04 Voltage mV
  5. cv05: Cell 05 Voltage mV
  6. cv06: Cell 06 Voltage mV
  7. cv07: Cell 07 Voltage mV
  8. cv08: Cell 08 Voltage mV
  9. cv09: Cell 09 Voltage mV
  10. cv10: Cell 10 Voltage mV
  11. cv11: Cell 11 Voltage mV
  12. cv12: Cell 12 Voltage mV
  13. cv13: Cell 13 Voltage mV
  14. cv14: Cell 14 Voltage mV
  15. cv15: Cell 15 Voltage mV
  16. cv16: Cell 16 Voltage mV
  17. cv17: Cell 17 Voltage mV
  18. cv18: Cell 18 Voltage mV
  19. cv19: Cell 19 Voltage mV
  20. cv20: Cell 20 Voltage mV
  21. cv21: Cell 21 Voltage mV
  22. cv22: Cell 22 Voltage mV
  23. cv23: Cell 23 Voltage mV
  24. pkt1: Pack Temperature-1 C
  25. pkt2: Pack Temperature-2 C
  26. pkt3: Pack Temperature-3 C
  27. pkt4: Pack Temperature-4 C
  28. pkt5: MOS Temperature C
  29. pkt6: Environment Temperature

This documentation should serve as a complete reference for configuring your device and understanding its payload. If you need further clarification, code integration, or additional sections (e.g., troubleshooting), let me know!