Introduction

This document describes the design framework of Quecel smart tracker in the QuecPython solution, including the software and hardware system framework, description of key components, introduction and functional examples of system initialization process and business process, to help you quickly understand the overall architecture and functions of Quectel smart tracker.

Overview

• Smart tracker
• Terminal device functions meet the majority of requirements in tracker application scenarios
• The visual operation platform and the mobile APP make device management and data viewing more convenient.

Functions

• Multi-technology positioning, geo-fence alarm, danger alarm, SOS alarm reporting, audio monitoring, recording, historical track playback, remote control, etc.
• Smart positioning
  • The system utilizes 4G communication/multi-technology positioning/distributed services to provide a one-stop solution from end to service for the smart tracker industry.
• All-platform support
  • The device operation platform and mobile APP have all-round functions, enabling terminal device manufacturers to quickly manage devices and end users without the need to build your own service platforms.
• Reliable and stable
  • The terminal device has high positioning accuracy, high sensitivity to danger perception, low power consumption, and stable operation. Terminal device manufacturers can develop customized solutions directly based on the public version, greatly shortening the hardware development cycle.

Features

• Intelligent perception, recognition, and reporting of location information and danger alarms.
• Support integration with various IoT platforms such as Alibaba IoT Platform, ThingsBoard, and other private services.
• Secondary development with QuecPython to formulate modular and customizable solutions, thus shortening development cycles.
• Visual operation platform and mobile APP to control terminal devices.

Applications

• Vehicle tracking
• Logistics and transportation
• People tracking
• Electronic student ID card
• Pet tracking
• Special industries (agricultural irrigation, rare species monitoring, etc.)

Application Framework

Function Overview

The software functions of smart tracker solution are demonstrated in the diagram below. The solution is divided into functions based on the actual business of the tracker and developed in a modular way.

• Transmission Protocol Parsing
  • Connection and data interaction with Alibaba IoT Platform
  • Connection and data interaction with ThingsBoard
  • GT06 protocol
  • JT/T808 protocol
• Network Management
  • MQTT protocol (Alibaba IoT/ThingsBoard/other platforms)
  • TCP/UDP protocol (GT06/JTT808 protocol)
  • APN settings (network registration and data call)
  • LTE NET (4G network registration and data call)
• Peripheral Management
  • GNSS: Turn on/off the GNSS module, read positioning data from the GNSS module, and inject AGPS data.
  • G-sensor: Read data of sensors
  • Charge IC: Charging management, obtaining device charging status
  • Battery: Battery management, reading battery voltage and calculating battery level
  • LED: LED indicator
• Data Storage
  • Storage of system configuration parameters
  • Storage of location data backup
  • AGPS download storage
  • Log information storage
• Device Upgrade
  • OTA upgrade
• Business Function Management
  • Connection and reconnection of network and IoT platforms
  • Device data acquisition and reporting
  • Alarm detection and reporting
  • Processing of IoT platform downlink commands
  • Device low power consumption

Data Interaction Process

The data interaction process between the module and the IoT platform is described in the following diagram.

Process description:

1. The mobile APP sends commands to the IoT platform. The server issues commands to the module through TCP/UDP/MQTT protocols, and the module parses the command data.
2. The module reports data to the IoT platform through TCP/UDP/MQTT protocols. The IoT platform processes the data and synchronously displays it on the mobile APP.

Design Philosophy and Patterns

• This system is designed as a listener pattern, that is, transmit messages and listen for events through callback functions.
• The software functions are split according to the tracker's business requirements, which are implemented based on functional modules. Each part is independently developed to reduce dependencies and can be debugged and run independently, thus achieving decoupling effects.
• Interactions between functions are realized through callback functions. All business function processing, such as downlink command processing, alarm detection, data acquisition and reporting, and device control, is done in the Tracker class.

1. All functional modules are registered in the Tracker class through Tracker.add_module.
2. The Server module (IoT platform interaction module) transmits service downlink data to Tracker.server_callback() for processing through callback functions.
3. The NetManage module transmits network disconnection events to Tracker.net_callback for processing through callback functions.

Software Architecture Diagram

The software system framework is described as follows:

• Display layer, connection with different IoT platforms
• Transport layer, data interaction over different protocols
• Business layer, mainly used for device data acquisition, device control, downlink commands receiving and processing of IoT platforms, and data integration and reporting.
• Device layer, functions including obtaining and parsing location data, reading sensor data, battery management and historical data storage, and device information acquisition and device functions setting, such as device version, IMEI number, APN settings, network data call and device low power consumption.

Business Process

Business Process Description:

1. Power on the device.
2. Configure APN and connect to the network (network registration and data call); Configure IoT platform and establish a connection, with retry on failure.
3. Detect the boot of objects and acquire data.
   • Power on the GNSS object and wait for positioning data.
   • Power on the G-Sensor and detect the calibration.
   • Turn on LED indicators (network status/positioning status/charging status, etc.).
   • Acquire battery level and detect charging status.
   • Detect alarms (overspeed/vibration/geo-fence/low battery level, etc.).
4. After connecting to the IoT platform, check if there is any historical data that needs to be reported and proceed with reporting.
5. Upon successful connection to the IoT platform, report current device information (location/alarms).
6. If the connection to the IoT platform fails, store the current device information (location/alarms).
7. When the device has no tasks, enter low power mode and wake up the device periodically to detect device information and report it.
8. After connecting to the IoT platform, wait for commands to be issued by the IoT platform
9. Parse commands
   • Device control commands, such as modifying device business parameters and controlling device shutdown or reboot.
   • OTA upgrade commands for OTA upgrades
   • Device information query commands, which should be responded with device information

System Initialization Process

1. Initialize basic functional objects, such as low power management, configuration parameters, battery, historical files, positioning, and sensors.
2. Initialize IoT platform server object, such as Alibaba IoT Platform, ThingsBoard, or other private service platform (GT06, JT/T808, etc.).
3. Initialize the core business object (Tracker), and add various functional objects to the Tracker object through tracker.add_module(), then register Tracker.server_callback() to the Server object for receiving downlink messages and commands from the server.

Application Development

Get Solution Resource

Tracker solution resources can be downloaded from https://github.com/QuecPython/solution-tracker

The solution project has a sub-project named modules. Do not forget to download the sub-project together.

The command for downloading the sub-project synchronously: git clone --recursive https://github.com/QuecPython/solution-tracker.git

Resource package directory:

• code

This directory contains the software solution code.

• docs

This directory contains project documents such as user guides and functional interface specifications.

• object_model_demo

This directory contains a TSL model file of the Alibaba IoT Platform, which can be directly imported into the Alibaba IoT Platform for debugging.

Solution Overview

This is a public version of the tracker solution, which does not include all functions. The solution provides the functional implementation of the core components of the tracker and functions such as data interaction, and event forwarding with the server. You can continue to develop business functions based on this framework. The current software framework has the following features:

• Data interaction over MQTT (Alibaba IoT Platform and ThingsBoard are supported currently.)
• Read and write configuration file
• OTA upgrade
• LED indicator
• Device network management
• Device information management
• Battery level and charging management
• Backup data storage
• GNSS positioning/LBS positioning/Wi-Fi positioning
• Low power management
• Log storage and recording

Set up Environment

Install USB Driver

Please download and install the driver according to the platform of the module to be debugged. Click here to download USB Drivers

Download Development and Debugging Tool

It is recommended to use QPYcom for development and debugging. The processes described in this document are under the premise that QPYcom is used and USB driver installation is successful.

Click here to download QPYcom

Click here to view QPYcom User Guide

Modify Code Configuration Parameters

The configuration parameters used in the current solution code are not configured. Please modify configurations according to the instructions below.

Find the configuration files starting with settings_ in the code folder and modify the configuration based on actual parameters, as shown below.

• settings_server.py is used to configure the IoT platform connection information.

class AliIotConfig:

    product_key = ""
    product_secret = ""
    device_name = ""
    device_secret = ""
    server = "iot-as-mqtt.cn-shanghai.aliyuncs.com"
    qos = 1


class ThingsBoardConfig:

    host = ""
    port = 1883
    username = ""
    qos = 0
    client_id = ""

• settings_loc.py is used to configure the information of the module used for positioning (UART port of the external GNSS communication, authentication information for LBS/Wi-Fi positioning).

gps_cfg = {
    "UARTn": UART.UART1,
    "buadrate": 115200,
    "databits": 8,
    "parity": 0,
    "stopbits": 1,
    "flowctl": 0,
    "gps_mode": _gps_mode.external,
    "nmea": 0b010111,
    "PowerPin": None,
    "StandbyPin": None,
    "BackupPin": None,
}

cell_cfg = {
    "serverAddr": "www.queclocator.com",
    "port": 80,
    "token": "xxxxxxxxxx",
    "timeout": 3,
    "profileIdx": profile_idx,
}

wifi_cfg = {
    "token": "xxxxxxxxxx"
}

• settings_user.py is used to configure parameters related to user business functions (e.g., alarm switch, low battery level threshold).

class _server:
    none = 0x0
    AliIot = 0x1
    ThingsBoard = 0x2

class _drive_behavior_code:
    none = 0x0
    sharply_start = 0x1
    sharply_stop = 0x2
    sharply_turn_left = 0x3
    sharply_turn_right = 0x4

class _ota_upgrade_module:
    none = 0x0
    sys = 0x1
    app = 0x2

debug = 1
log_level = "DEBUG"
checknet_timeout = 60
server = _server.AliIot
phone_num = ""
low_power_alert_threshold = 20
low_power_shutdown_threshold = 5
over_speed_threshold = 50
sw_ota = 1
sw_ota_auto_upgrade = 1
sw_voice_listen = 0
sw_voice_record = 0
sw_fault_alert = 1
sw_low_power_alert = 1
sw_over_speed_alert = 1
sw_sim_abnormal_alert = 1
sw_disassemble_alert = 1
sw_drive_behavior_alert = 1
drive_behavior_code = _drive_behavior_code.none
loc_method = _loc_method.all
loc_gps_read_timeout = 300
work_mode = _work_mode.cycle
work_mode_timeline = 3600
work_cycle_period = 30
user_ota_action = -1
ota_status = {
    "sys_current_version": "",
    "sys_target_version": "--",
    "app_current_version": "",
    "app_target_version": "--",
    "upgrade_module": _ota_upgrade_module.none,
    "upgrade_status": _ota_upgrade_status.none,
}

Download Firmware

Download the corresponding QuecPython firmware according to the current debugging module model from the QuecPython official website, and download the firmware into the module with QPYcom.

Click here to download firmware

Use QPYcom to download firmware.

1. Select firmware

2. Download firmware

3. Wait for the completion of firmware download

4. Successful download

5. Connect to the interactive port

6. View the download information

Download Code

• It is recommended to rename the main.py file to _main.py before downloading the code because the main.py file will run automatically when the module is powered on, which is not convenient for debugging. During the test, we can manually run the _main.py file for easier debugging.

• When downloading the code via USB, you need to reserve a USB port or test point for the device. Or you can use an EVB for debugging, and install the driver in advance.

1. Select "Quectel USB NMEA PORT". This serial port is for interaction, and QPYcom logs will also be output through this serial port.

2. Download the business functional code to the device in batches. Click "Download script" and wait for the download to complete. After the download is complete, view the result on the "File" page.

3. After successful download, it is recommended to reboot the device and run the function (If the main.py file was downloaded, the function will run automatically after the device is rebooted; if the main.py file was renamed to _main.py before downloading, you need to manually run the _main.py file to start the function).

4. View the running result

Electricity Meter

HeliosSDK