Skip to main content

POST /api/devices/{deviceId}/sendCommand

This endpoint allows you to send a command to a specific device in the satellite tracking application. It is useful for executing remote instructions or sending specific configuration to the device.

Request Details​

The request is made using the POST method at the /api/devices/{deviceId}/sendCommand URL. You must replace {deviceId} with the actual ID of the device you want to send the command to.

Request Parameters​

This endpoint requires the deviceId parameter to be included in the URL path.

ParameterTypeRequiredDescription
deviceIdstringYesThe unique identifier of the device to send the command to.

Request Body Parameters​

The body of the request must include a JSON object with the command data for the device.

FieldTypeRequiredDescription
commandstringYesThe command to send to the device.
formatstringNoFormat of the command string. Can be one of the following:
- Text: The command is a plain string.
- Hex: The command is a hexadecimal string.
- Base64: The command is a Base64 encoded string.
Defaults to Text.
smsbooleanNoIf true, the command is sent via SMS. If false (or omitted), the command is sent via GPRS to the device.

Command Formats and Delivery Method​

This endpoint supports different formats for the command string and two methods of delivery. Understanding these options ensures the command is correctly interpreted by the physical device.

1. Command Formats (format)​

The format parameter dictates how the string provided in the command field will be decoded before it is sent to the device.

  • Text (Default): The command is treated as plain text. It is sent exactly as typed, encoded as UTF-8.

    • Example use case: Sending a human-readable instruction like an engine cutoff command.
    • Example payload: 
      {
        "command": "engine_stop",
        "format": "Text"
      }

  • Hex: The command represents binary data encoded as a hexadecimal string. This is useful for devices that require raw byte commands (e.g., proprietary protocol packets). Spaces or hyphens in the string are allowed and will be automatically safely ignored.

    • Example use case: Sending raw bytes to configure a hardware parameter.
    • Example payload: 
      {
        "command": "0A 1B 2C",
        "format": "Hex"
      }

  • Base64: The command represents binary data encoded in Base64 format. This is another way to safely transmit binary streams inside a JSON object.

    • Example use case: Sending a longer binary payload or a file generated by another system.
    • Example payload: 
      {
        "command": "SGVsbG8=",
        "format": "Base64"
      }

2. Delivery Method (sms)​

The sms parameter determines the communication channel used to route the command to the tracking device.

  • GPRS (Default / sms: false): The command is sent using the device's internet data connection (TCP/UDP). This is the standard method for an active device and is generally faster.
  • SMS (sms: true): The command is delivered to the device via a standard text message. This is useful when the device is out of GPRS internet coverage or is in a deep sleep mode without active data connections, but is still connected to the cellular phone network.

Authentication Required​

Authentication required to use the endpoint is via a Bearer token. This authentication method implies that each request must include an authorization header with a valid access token. This Bearer token acts as a credential that verifies the identity of the user or application making the request, ensuring that only authorized entities can modify the user's information. By requiring this type of authentication, the system guarantees a high level of security and access control, protecting users' data against unauthorized access.

Example Request​

POST /api/devices/device123/sendCommand HTTP/1.1
Host: api.plaspy.com
Authorization: Bearer {token}
Content-Type: application/json

{
  "command": "engine_stop",
  "format": "Text",
  "sms": false
}

Response Parameters​

The response from this endpoint includes details about the success of the operation and any errors that may have occurred.

FieldTypeRequiredDescription
successbooleanYesIndicates whether the request was successful.
errorstringNoError message in case the request fails.
apiUsageintegerNoAPI usage in the current request.
apiDailyUsageintegerNoDaily API usage.
resultstringNoThe result or response of the command execution.

Example Successful Response​

{
  "success": true,
  "apiUsage": 150,
  "apiDailyUsage": 3000,
  "result": "Command executed successfully"
}

Example Error Response​

Error 400 (Bad Request) Response​

{
  "success": false,
  "error": "Bad Request",
  "apiUsage": 150,
  "apiDailyUsage": 3000
}

Error 500 (Internal Server Error) Response​

{
  "success": false,
  "error": "Internal Server Error",
  "apiUsage": 150,
  "apiDailyUsage": 3000
}

This endpoint is essential for managing device functions remotely. It allows users to send explicit commands and receive the corresponding results, ensuring complete control over the device.

Plaspy GPS Tracking Platform

Explore the Plaspy platform and compatible GPS devices

Browse technical guides, application documentation, compatible trackers, and setup resources to get more value from Plaspy.

Visit PlaspyBrowse compatible devices