Http_response_code

  1. Http Response Code 401
  2. Http Response Code 503
-->

This has the same semantics as the 302 Found HTTP response code, with the exception that the user agent must not change the HTTP method used: If a POST was used in the first request, a POST must be used in the second request. 308 Permanent Redirect.

  1. Httpresponsecode function (PHP = 5.4) The httpresponsecode function was introduced in PHP 5.4, and it made things a lot easier. Httpresponsecode(404); That's all. Here is a function that I have cooked up when I needed compatibility below 5.4 but wanted the functionality of the 'new' httpresponsecode function.
  2. This has the same semantics as the 302 Found HTTP response code, with the exception that the user agent must not change the HTTP method used: If a POST was used in the first request, a POST must be used in the second request. 308 Permanent Redirect.
  3. The Removals tool enables you to temporarily block pages from Google Search results on sites that you own, see a history of removal requests from both property owners and non-owners, and also to see any URLs on your site that were reported as containing adult content.
  4. This is a list of Hypertext Transfer Protocol (HTTP) response status codes. Status codes are issued by a server in response to a client's request made to the server. It includes codes from IETF Request for Comments (RFCs), other specifications, and some additional codes used in some common applications of the HTTP.

This article applies to device developers.

A device template in Azure IoT Central is a blueprint that defines the:

Code
  • Telemetry a device sends to IoT Central.
  • Properties a device synchronizes with IoT Central.
  • Commands that IoT Central calls on a device.

This article describes, for device developers, the JSON payloads that devices send and receive for telemetry, properties, and commands defined in a device template.

The article doesn't describe every possible type of telemetry, property, and command payload, but the examples illustrate all the key types.

Each example shows a snippet from the device model that defines the type and example JSON payloads to illustrate how the device should interact with the IoT Central application.

Note

IoT Central accepts any valid JSON but it can only be used for visualizations if it matches a definition in the device model. You can export data that doesn't match a definition, see Export IoT data to destinations in Azure.

The JSON file that defines the device model uses the Digital Twin Definition Language (DTDL) v2.

For sample device code that shows some of these payloads in use, see the Create and connect a client application to your Azure IoT Central application tutorial.

View raw data

IoT Central lets you view the raw data that a device sends to an application. This view is useful for troubleshooting issues with the payload sent from a device. To view the raw data a device is sending:

  1. Navigate to the device from the Devices page.

  2. Select the Raw data tab:

    On this view, you can select the columns to display and set a time range to view. The Unmodeled data column shows data from the device that doesn't match any property or telemetry definitions in the device template.

Telemetry

Telemetry in components

If the telemetry is defined in a component, add a custom message property called $.sub with the name of the component as defined in the device model. To learn more, see Tutorial: Create and connect a client application to your Azure IoT Central application.

Primitive types

This section shows examples of primitive telemetry types that a device streams to an IoT Central application.

The following snippet from a device model shows the definition of a boolean telemetry type:

A device client should send the telemetry as JSON that looks like the following example:

The following snippet from a device model shows the definition of a string telemetry type:

A device client should send the telemetry as JSON that looks like the following example:

The following snippet from a device model shows the definition of an integer telemetry type:

A device client should send the telemetry as JSON that looks like the following example:

The following snippet from a device model shows the definition of a double telemetry type:

A device client should send the telemetry as JSON that looks like the following example:

The following snippet from a device model shows the definition of a dateTime telemetry type:

A device client should send the telemetry as JSON that looks like the following example - DateTime types must be in ISO 8061 format:

The following snippet from a device model shows the definition of a duration telemetry type:

A device client should send the telemetry as JSON that looks like the following example - durations must be in ISO 8601 format:

Complex types

This section shows examples of complex telemetry types that a device streams to an IoT Central application.

The following snippet from a device model shows the definition of a geopoint telemetry type:

Note

The geopoint schema type is not part of the Digital Twins Definition Language specification. IoT Central currently supports the geopoint schema type and the location semantic type for backwards compatibility.

A device client should send the telemetry as JSON that looks like the following example. IoT Central displays the value as a pin on a map:

The following snippet from a device model shows the definition of an Enum telemetry type:

A device client should send the telemetry as JSON that looks like the following example. Possible values are 0, 1, and 2 that display in IoT Central as Item1, Item2, and Item3:

The following snippet from a device model shows the definition of an Object telemetry type. This object has three fields with types dateTime, integer, and Enum:

A device client should send the telemetry as JSON that looks like the following example. DateTime types must be ISO 8061 compliant. Possible values for Property3 are 0, 1, and that display in IoT Central as Item1, Item2, and Item3:

The following snippet from a device model shows the definition of a vector telemetry type:

A device client should send the telemetry as JSON that looks like the following example:

Event and state types

This section shows examples of telemetry events and states that a device sends to an IoT Central application.

The following snippet from a device model shows the definition of a integer event type:

A device client should send the event data as JSON that looks like the following example:

The following snippet from a device model shows the definition of a integer state type:

A device client should send the state as JSON that looks like the following example. Possible integer state values are 1, 2, or 3:

Properties

Note

The payload formats for properties applies to applications created on or after 07/14/2020.

Properties in components

If the property is defined in a component, wrap the property in the component name. The following example sets the maxTempSinceLastReboot in the thermostat2 component. The marker __t indicates that this a component:

To learn more, see Tutorial: Create and connect a client application to your Azure IoT Central application.

Primitive types

This section shows examples of primitive property types that a device sends to an IoT Central application.

The following snippet from a device model shows the definition of a boolean property type:

A device client should send a JSON payload that looks like the following example as a reported property in the device twin:

The following snippet from a device model shows the definition of a boolean property type:

A device client should send a JSON payload that looks like the following example as a reported property in the device twin:

The following snippet from a device model shows the definition of a date property type:

A device client should send a JSON payload that looks like the following example as a reported property in the device twin. Date types must be ISO 8061 compliant:

The following snippet from a device model shows the definition of a duration property type:

A device client should send a JSON payload that looks like the following example as a reported property in the device twin - durations must be ISO 8601 Duration compliant:

The following snippet from a device model shows the definition of a float property type:

A device client should send a JSON payload that looks like the following example as a reported property in the device twin:

The following snippet from a device model shows the definition of a string property type:

A device client should send a JSON payload that looks like the following example as a reported property in the device twin:

Http Response Code 401

Complex types

This section shows examples of complex property types that a device sends to an IoT Central application.

The following snippet from a device model shows the definition of a geopoint property type:

Note

The geopoint schema type is not part of the Digital Twins Definition Language specification. IoT Central currently supports the geopoint schema type and the location semantic type for backwards compatibility.

A device client should send a JSON payload that looks like the following example as a reported property in the device twin:

The following snippet from a device model shows the definition of an Enum property type:

A device client should send a JSON payload that looks like the following example as a reported property in the device twin. Possible values are 0, 1, and that display in IoT Central as Item1, Item2, and Item3:

The following snippet from a device model shows the definition of an Object property type. This object has two fields with types string and integer:

A device client should send a JSON payload that looks like the following example as a reported property in the device twin:

The following snippet from a device model shows the definition of an vector property type:

Http_response_code always returns 200

A device client should send a JSON payload that looks like the following example as a reported property in the device twin:

Writable property types

This section shows examples of writable property types that a device receives from an IoT Central application.

If the writable property is defined in a component, the desired property message includes the component name. The following example shows the message requesting the device to update the targetTemperature in the thermostat2 component. The marker __t indicates that this a component:

To learn more, see Tutorial: Create and connect a client application to your Azure IoT Central application.

IoT Central expects a response from the device to writable property updates. The response message should include the ac and av fields. The ad field is optional. See the following snippets for examples.

ac is a numeric field that uses the values in the following table:

ValueLabelDescription
'ac': 200CompletedThe property change operation was successfully completed.
'ac': 202 or 'ac': 201PendingThe property change operation is pending or in progress
'ac': 4xxErrorThe requested property change wasn't valid or had an error
'ac': 5xxErrorThe device experienced an unexpected error when processing the requested change.

av is the version number sent to the device.

ad is an option string description.

The following snippet from a device model shows the definition of a writable string property type:

The device receives the following payload from IoT Central:

The device should send the following JSON payload to IoT Central after it processes the update. This message includes the version number of the original update received from IoT Central. When IoT Central receives this message, it marks the property as synced in the UI:

The following snippet from a device model shows the definition of a writable Enum property type:

The device receives the following payload from IoT Central:

The device should send the following JSON payload to IoT Central after it processes the update. This message includes the version number of the original update received from IoT Central. When IoT Central receives this message, it marks the property as synced in the UI:

Commands

If the command is defined in a component, the name of the command the device receives includes the component name. For example, if the command is called getMaxMinReport and the component is called thermostat2, the device receives a request to execute a command called thermostat2*getMaxMinReport.

The following snippet from a device model shows the definition of a command that has no parameters and that doesn't expect the device to return anything:

The device receives an empty payload in the request and should return an empty payload in the response with a 200 HTTP response code to indicate success.

The following snippet from a device model shows the definition of a command that has an integer parameter and that expects the device to return an integer value:

The device receives an integer value as the request payload. The device should return an integer value as the response payload with a 200 HTTP response code to indicate success.

The following snippet from a device model shows the definition of a command that has an object parameter and that expects the device to return an object. In this example, both objects have integer and string fields:

The following snippet shows an example request payload sent to the device:

The following snippet shows an example response payload sent from the device. Use a 200 HTTP response code to indicate success:

Long running commands

The following snippet from a device model shows the definition of a command. The command has an integer parameter and expects the device to return an integer value:

The device receives an integer value as the request payload. If the device needs time to process this command, it should return an empty response payload with a 202 HTTP response code to indicate the device has accepted the request for processing.

When the device has finished processing the request, it should send a property to IoT Central that looks like the following example. The property name must be the same as the command name:

Offline commands

In the IoT Central web UI, you can select the Queue if offline option for a command. Offline commands are one-way notifications to the device from your solution that are delivered as soon as a device connects. Offline commands can have a request parameter but don't return a response.

The Queue if offline setting isn't included if you export a model or interface from the device template. You can't tell by looking at an exported model or interface JSON that a command is an offline command.

Offline commands use IoT Hub cloud-to-device messages to send the command and payload to the device.

The payload of the message the device receives is the raw value of the parameter. A custom property called method-name stores the name of the IoT Central command. The following table shows some example payloads:

IoT Central request schemaExample payload received by device
No request parameter@
Double1.23
Stringsample string
Object{'StartTime':'2021-01-05T08:00:00.000Z','Bank':2}

The following snippet from a device model shows the definition of a command. The command has an object parameter with a datetime field and an enumeration:

Http Response Code 503

If you enable the Queue if offline option in the device template UI for the command in the previous snippet, then the message the device receives includes the following properties:

Property nameExample value
custom_properties{'method-name': 'GenerateDiagnostics'}
data{'StartTime':'2021-01-05T08:00:00.000Z','Bank':2}

Next steps

As a device developer, now that you've learned about device templates, a suggested next steps is to read Get connected to Azure IoT Central to learn more about how to register devices with IoT Central and how IoT Central secures device connections.

If your version of PHP does not include this function:
<?php
if (!function_exists('http_response_code')) {
function
http_response_code($code = NULL) {
if (
$code ! NULL) {
switch (
$code) {
case
100: $text = 'Continue'; break;
case
101: $text = 'Switching Protocols'; break;
case
200: $text = 'OK'; break;
case
201: $text = 'Created'; break;
case
202: $text = 'Accepted'; break;
case
203: $text = 'Non-Authoritative Information'; break;
case
204: $text = 'No Content'; break;
case
205: $text = 'Reset Content'; break;
case
206: $text = 'Partial Content'; break;
case
300: $text = 'Multiple Choices'; break;
case
301: $text = 'Moved Permanently'; break;
case
302: $text = 'Moved Temporarily'; break;
case
303: $text = 'See Other'; break;
case
304: $text = 'Not Modified'; break;
case
305: $text = 'Use Proxy'; break;
case
400: $text = 'Bad Request'; break;
case
401: $text = 'Unauthorized'; break;
case
402: $text = 'Payment Required'; break;
case
403: $text = 'Forbidden'; break;
case
404: $text = 'Not Found'; break;
case
405: $text = 'Method Not Allowed'; break;
case
406: $text = 'Not Acceptable'; break;
case
407: $text = 'Proxy Authentication Required'; break;
case
408: $text = 'Request Time-out'; break;
case
409: $text = 'Conflict'; break;
case
410: $text = 'Gone'; break;
case
411: $text = 'Length Required'; break;
case
412: $text = 'Precondition Failed'; break;
case
413: $text = 'Request Entity Too Large'; break;
case
414: $text = 'Request-URI Too Large'; break;
case
415: $text = 'Unsupported Media Type'; break;
case
500: $text = 'Internal Server Error'; break;
case
501: $text = 'Not Implemented'; break;
case
502: $text = 'Bad Gateway'; break;
case
503: $text = 'Service Unavailable'; break;
case
504: $text = 'Gateway Time-out'; break;
case
505: $text = 'HTTP Version not supported'; break;
default:
exit(
'Unknown http status code ' . htmlentities($code) . '');
break;
}
$protocol = (isset($_SERVER['SERVER_PROTOCOL']) ? $_SERVER['SERVER_PROTOCOL'] : 'HTTP/1.0');
header($protocol . ' ' . $code . ' ' . $text);
$GLOBALS['http_response_code'] = $code;
} else {
$code = (isset($GLOBALS['http_response_code']) ? $GLOBALS['http_response_code'] : 200);
}
return
$code;
}
}
?>

In this example I am using $GLOBALS, but you can use whatever storage mechanism you like... I don't think there is a way to return the current status code:
https://bugs.php.net/bug.php?id=52555
For reference the error codes I got from PHP's source code:
http://lxr.php.net/opengrok/xref/PHP_5_4/sapi/cgi/cgi_main.c#354
And how the current http header is sent, with the variables it uses:
http://lxr.php.net/opengrok/xref/PHP_5_4/main/SAPI.c#856