Device Management

The Audiogum platform provides various device APIs for managing firmware releases, capturing registrations or gathering logs.

Device details

The above APIs allow registering devices (speakers, phones etc.) against users as well as uploading details about devices for diagnostics purposes.

Details can be supplied either by an app when registering against a user (PUT /v1/user/devices/{deviceid}) or by device firmware directly (PUT /v1/devices/{deviceid}). In either case, requests must be appropriately authenticated - see authentication for details.

Details can be omitted if not relevant, the only strictly mandatory field is deviceid. Most fields values are either string or integer form as per example.

Example device details JSON (speaker)

{
  "deviceid": "DEVICEID1",
  "devicetype": "Device Type",
  "brand": "SmartDevice100",
  "serial": "SERIALNUMBER1",
  "devicename": "George's 100",
  "purchase": {
    "country": "dk",
    "point-of-sale": "retailer",
    "date": "2017-07-28"
  },
  "warranty": {
    "extended": true,
    "expires": "2018-01-28"
  },
  "versioninfo": {
    "firmware": "123",
    "module": "1.2.3.4",
    "mcu": "1.2.3.4",
    "dsp": "1.2.3.4",
    "bt": "1.2.3.4"
  },
  "power": {
    "bootcount": 6,
    "runtime": 124,
    "batteryruntime": 35,
    "powersupplyruntime": 89,
    "chargingtime": 221
  },
  "presets": [
    {
      "presetnumber": 1,
      "ref": "199458",
      "service": "xmly",
      "name": "黑猫警长系列故事"
    },
    {
      "presetnumber": 5,
      "ref": "1343",
      "service": "vtuner",
      "name": "Radio Guangdong Music 99.3 FM"
    }
  ]
}

Example device details JSON (phone)

{
    "deviceid": "FA46RWM11137",
    "devicetype": "phone",
    "devicename": "HTC One_M8",
    "devicemanufacturer": "HTC",
    "platform": "android",
    "platformversion": "6.0",
    "location": {
       "city": "Dublin",
       "country": "Ireland"
    },
    "countrycode": "ie",
    "locale": {
       "country": "GB",
       "language": "en"
    }
}

Note that as per speaker data, all fields other than deviceid are optional.

Registering a device

The PUT /v1/user/devices/owner/{deviceid} endpoint can be used to set an ownership relation between a user and a device, this is useful to indicate that a device is registered to a user. A user can own multiple devices but a device can only be owned by one user. If a device already has an owner you will receive a 409 response code.

The DELETE /v1/user/devices/owner/{deviceid} endpoint can be used to remove an ownership relation or effectively deregister a device (useful for example when a user sells a device to someone else). This will allow a new user to register the device.

Device logs

For the purpose of diagnosing specific user issues with a device, files such as debug logs or crash dump data can be uploaded to the API: POST /v1/devices/{deviceid}/logs/{logtype}

Note that this endpoint accepts standard multipart file upload requests, as illustrated by the following curl request:

curl -X POST --header 'Content-Type: multipart/form-data' --header 'Accept: application/json' --header 'Authorization: Bearer YOURTOKEN' -F "file=@/YOUR/FILE/PATH/FILENAME.zip;type=application/zip" 'https://api.audiogum.com/v1/devices/DEVICEID/logs/TYPE'

where the following are placeholders:

• YOURTOKEN is the bearer token acquired through authentication
• /YOUR/FILE/PATH/FILENAME.zip is the path and filename of the file locally on the device
• DEVICEID is the deviceid of the device as per the device details
• TYPE is the type of log file. This can be used to identify different kinds of file, for example crashdump or log.

This API limits the data uploaded as follows:

• Files must be of type zip (application/zip)
• Total file size must be less than 1MB

Firmware

The audiogum API supports specifying and querying device firmware.

Firmware Schema

When adding firmware there are number of parameters you can use to match devices to specific firmware versions:

When a device is checking for firmware updates against GET /v1/devices/firmware it will receive a 200 response with a single firmware record if an update is available or a 404 if there is no update available for the device.