Devices

The Audiogum platform provides various device APIs:

APIPurpose
GET /v1/devices/firmwareFirmware Version Checking
PUT /v1/user/devices/{deviceid}Register device details against user. See Device details
GET /v1/devices?serial={serial}Get device details
GET /v1/user/devicesList devices for user
PUT /v1/devices/{deviceid}Update device details direct from device without app. See Device details
GET /v1/devices/{deviceid}Get device details
PUT /v1/user/devices/owner/{deviceid}Assign user as owner of device.
DELETE /v1/user/devices/owner/{deviceid}Unassign user as owner of device.
GET /v1/user/devices/ownerList devices owned by User.
POST /v1/devices/{deviceid}/logs/{logtype}Upload device log and crash info files. See Log files

Device details

The above APIs allow registering devices (speakers, phones etc) against users and also 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.

In either case the data accepted is the same, as illustrated in the example below. 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. Some strings require specific enumerated values as follows:

FieldAllowed values
wifi.currentmodesta, ap
soundspaces.currentmodemaster, slave
soundspaces.currentchannell, r, stereo

Note: The same API can be used to supply phone info for a user, not only speakers.

Example device details JSON (speaker)

{
    "deviceid": "DEVICEID1",
    "devicetype": "Device Type",
    "brand": "SmartDevice100",
    "serial": "SERIALNUMBER1",
    "friendlyname": "George's 100",
    "friendlynamechangecount": 1,
    "region": "region",
	"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
    },
    "wifi": {
	    "setapcount": 2,
	    "disconnectcount": 3,
	    "successconnectcount": 4,
	    "apmodetime": 23,
	    "stamodetime": 102,
	    "stats": {
	        "txbytes": 21342,
	        "rxbytes": 645345,
	        "txpackets": 3265,
	        "rxpackets": 75323,
	        "txpacketsdropped": 124,
	        "rxpacketsdropped": 53,
	        "txpacketserror": 12,
	        "rxpacketserror": 0
	    },
	    "currentnetworkspeed": 324,
	    "currentmode": "ap",
	    "currentchannel": 6,
	    "currentroutermac": "6c:40:08:b5:7b:56",
	    "currentrouterip": "192.168.12.1",
	    "currentrssi": 21,
	    "currentsnr": 12
    },
    "bt": {
	    "successconnectcount": 4
    },
    "player": {
	    "airplayplaycount": 0,
	    "airplaytime": 0,
	    "dlnaplaycount": 0,
	    "dlnatime": 0,
	    "qplayplaycount": 0,
	    "qplaytime": 0,
	    "btplaycount": 3,
	    "bttime": 22,
	    "usbplaycount": 2,
	    "usbtime": 10,
	    "auxplaycount": 0,
	    "auxtime": 0,
	    "udiskplaycount": 0,
	    "udisktime": 0,
	    "presetplaycount": 2,
	    "presettime": 12
    },
    "presets": [
	{
	    "presetnumber": 1,
	    "ref": "199458",
	    "service": "xmly",
	    "name": "黑猫警长系列故事"
	},
	{
	    "presetnumber": 5,
	    "ref": "1343",
	    "service": "vtuner",
	    "name": "Radio Guangdong Music 99.3 FM"
	}
    ],
    "soundspaces": {
	    "appsetupcount": 4,
	    "devicesetupcount": 0,
	    "appcancelcount": 4,
	    "devicecancelcount": 0,
	    "setstereocount": 2,
	    "stereotime": 32,
	    "setlchannelcount": 0,
	    "lchanneltime": 0,
	    "setrchannelcount": 0,
	    "rchanneltime": 0,
	    "currentdevices": 2,
	    "groupid": "abc123def",
	    "currentmode": "master",
	    "currentchannel": "stereo"
    },
    "settings": {
	    "seteqcount": 1,
	    "eqstats": [
	    {
		    "id": "V100",
		    "name": "Neutral",
		    "count": 1
	    },
	    {
		    "id": "...",
		    "name": "...",
		    "count": 0
	    }
	    ],
	    "setenvironmentcount": 0,
	    "environmentstats": [
	    {
		    "id": "...",
		    "name": "...",
		    "count": 0
	    }
	    ],
	    "currenteq": {
	        "id": "V100",
	        "name": "Normal"
	    },
	    "currentenvironment": {
	        "id": "...",
	        "name": "..."
	    }
    }
}

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",
       "latitude": 53.3331,
       "longitude": -6.2489
    },
    "countrycode": "ie",
    "locale": {
       "country": "GB",
       "language": "en"
    },
    "preferredlanguages": ["en-GB"],
    "ip": "54.72.124.122"
}

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.

APIPurpose
GET /v1/firmwareGets all firmware versions
POST /v1/firmwareAdd firmware version information
DELETE /v1/firmwareDelete firmware version information
GET /v1/devices/firmwareFirmware Version Checking

Firmware Schema

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

ParameterTypeDescription
downloadurlstringWhere to download the firmware from
devicetypestringA simple way to distinguish what type of device is requesting firmware
regionstringRegion code
versionstringFirmware version
releasenotesArray[ Map{ lang: String, body: String } ], optionalSpecify release notes for a firmware release in multiple languages
serial-regexstring, optionalCan be used to match against device serial numbers
mandatoryboolean, optionalWhether the firmware version must be downloaded even if more recent versions are available
testboolean, optionalCan be used for test firmware or to test against the firmware api

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.