Awesome
Microsoft Azure IoT SDKs for Java
2.0.0 clients release notice
A 2.0.0 release has been published for each package in this library. With this release, all future features will be brought only to this new major version, so users are highly encouraged to migrate from the 1.X.X releases to the new 2.0.0 releases. We have released one final LTS release for the 1.X.X packages that will be supported like any other LTS release.
If you need any help migrating your code to try out the new 2.X.X clients, please see this migration guide.
Critical upcoming change notice
All Azure IoT SDK users are advised to be aware of upcoming TLS certificate changes for Azure IoT hub and Device Provisioning Service that will impact the SDK's ability to connect. In October 2022, both services will migrate from the current Baltimore CyberTrust CA Root to the DigiCert Global G2 CA root. There will be a transition period beforehand where your IoT devices must have both the Baltimore and Digicert public certificates installed in their certificate store in order to prevent connectivity issues.
For a more in depth explanation as to why the IoT services are doing this, please see this article.
Users of this Java IoT SDK in particular will need to follow slightly different instructions in order to handle this upcoming change. See this document for a more in depth explanation of how to prepare your devices for this certificate migration.
Users who don't follow these instructions will begin experiencing unrecoverable, consistent connection failures from their devices starting June 2022.
If you have any questions, comments, or concerns about this upcoming change, please let us know on our discussions page.
Build status
Due to security considerations, build logs are not publicly available.
| Service Environment | Status |
|---|---|
| Main | |
| Preview |
This repository contains the following:
- Azure IoT Hub device SDK for Java: connect client devices to Azure IoT Hub
- Azure IoT Device Provisioning device SDK for Java: provision devices to Azure IoT Hub using Azure IoT Device Provisioning
- Azure IoT Device Provisioning service SDK for Java: manage your Provisioning service instance from a back-end Java application
Note that the IoT Hub service SDK has been moved to this repo.
To find SDKs in other languages for Azure IoT, please refer to the azure-iot-sdks repository
Developing applications for Azure IoT
Visit Azure IoT Dev Center to learn more about developing applications for Azure IoT.
How to use the Azure IoT SDKs for Java
Devices and data sources in an IoT solution can range from a simple network-connected sensor to a powerful, standalone computing device. Devices may have limited processing capability, memory, communication bandwidth, and communication protocol support. The IoT device SDKs enable you to implement client applications for a wide variety of devices.
- On Linux and Windows:
- Using Maven: the simplest way to use the Azure IoT SDKs for Java to develop apps is to leverage Maven packages:
- Clone the repository:
git clone https://github.com/Azure/azure-iot-sdk-java.git - Working with the SDKs code: if you are working with the SDKs code to modify it or contribute changes, then you can clone the repository and build the libraries:
- On Android: our Java device SDK can be used on Android:
For more details on what platforms this SDK supports, see this document.
API reference
- Azure IoT Hub device SDK
- Azure IoT Hub Device Provisioning device SDK
- Azure IoT Hub Device Provisioning service SDK
Key features and roadmap
Device client SDK
:heavy_check_mark: feature available :heavy_multiplication_x: feature planned but not supported :heavy_minus_sign: no support planned
| Features | mqtt | mqtt-ws | amqp | amqp-ws | https | Description |
|---|---|---|---|---|---|---|
| Authentication | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | Connect your device to IoT Hub securely with supported authentication, including private key, SASToken, X-509 Self Signed over MQTT, AMQPS and HTTPS, and X-509 Certificate Authority (CA) Signed. |
| Send device-to-cloud message | :heavy_check_mark:* | :heavy_check_mark:* | :heavy_check_mark:* | :heavy_check_mark:* | :heavy_check_mark: | Send device-to-cloud messages (max 256KB) to IoT Hub with the option to add custom properties. *IoT Hub supports batch send over AMQP and HTTPS at the moment, Java SDK only supports HTTPS. The MQTT and AMQP implementation loops over the batch and sends each message individually. |
| Receive cloud-to-device messages | :heavy_check_mark:* | :heavy_check_mark:* | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | Receive cloud-to-device messages and read associated custom and system properties from IoT Hub, with the option to complete/reject/abandon C2D messages. *IoT Hub does not support option to reject/abandon C2D messages over MQTT at the moment. |
| Device Twins | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_minus_sign: | IoT Hub persists a device twin for each device that you connect to IoT Hub. The device can perform operations like get twin tags, subscribe to desired properties. |
| Direct Methods | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_minus_sign: | IoT Hub gives you the ability to invoke direct methods on devices from the cloud. The SDK supports handler for generic operation. |
| Upload file to Blob | :heavy_minus_sign: | :heavy_minus_sign: | :heavy_minus_sign: | :heavy_minus_sign: | :heavy_check_mark: | A device can initiate a file upload and notifies IoT Hub when the upload is complete. File upload requires HTTPS connection, but can be initiated from client using any protocol for other operations such as telemetry. |
| Connection Status and Error reporting | :heavy_multiplication_x: | :heavy_multiplication_x: | :heavy_multiplication_x: | :heavy_multiplication_x: | :heavy_multiplication_x: | Error reporting for IoT Hub supported error code. |
| Retry policies | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | Retry policy for unsuccessful device-to-cloud messages have three options: no try, exponential backoff with jitter (default) and custom. Detail implementation is documented here. |
| Devices multiplexing over single connection | :heavy_minus_sign: | :heavy_minus_sign: | :heavy_check_mark: | :heavy_check_mark: | :heavy_multiplication_x: | |
| Connection Pooling * Specifying number of connections | :heavy_minus_sign: | :heavy_minus_sign: | :heavy_multiplication_x: | :heavy_multiplication_x: | :heavy_multiplication_x: |
Provisioning client SDK
:heavy_check_mark: feature available :heavy_multiplication_x: feature planned but not supported :heavy_minus_sign: no support planned This repository contains provisioning device client SDK for the Device Provisioning Service.
| Features | mqtt | mqtt-ws | amqp | amqp-ws | https | Description |
|---|---|---|---|---|---|---|
| TPM Individual Enrollment | :heavy_minus_sign: | :heavy_minus_sign: | :heavy_check_mark: | :heavy_multiplication_x: | :heavy_check_mark: | This SDK supports connecting your device to the Device Provisioning Service via individual enrollment using Trusted Platform Module. Please visit the samples folder and this quickstart on how to create a device client. Websocket connection over AMQP is currently not available. TPM over MQTT is currently not supported by the Device Provisioning Service. |
| X.509 Individual Enrollment | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | This SDK supports connecting your device to the Device Provisioning Service via individual enrollment using X.509 leaf certificate. Please visit the samples folder and this quickstart on how to create a device client. |
| X.509 Enrollment Group | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | This SDK supports connecting your device to the Device Provisioning Service via enrollment group using X.509 root certificate. Please visit the samples folder to learn more about this feature. |
Provisioning service client SDK
This repository contains provisioning service client SDK for the Device Provisioning Service to programmatically enroll devices.
| Feature | Support | Description |
|---|---|---|
| CRUD Operation with TPM Individual Enrollment | :heavy_check_mark: | Programmatically manage device enrollment using TPM with the service SDK. Please visit the samples folder and this quickstart to learn more about this feature. |
| Bulk CRUD Operation with TPM Individual Enrollment | :heavy_check_mark: | Programmatically bulk manage device enrollment using TPM with the service SDK. Please visit the samples folder to learn more about this feature. |
| CRUD Operation with X.509 Individual Enrollment | :heavy_check_mark: | Programmatically manage device enrollment using X.509 individual enrollment with the service SDK. Please visit the samples folder and this quickstart to learn more about this feature. |
| CRUD Operation with X.509 Group Enrollment | :heavy_check_mark: | Programmatically manage device enrollment using X.509 group enrollment with the service SDK. Please visit the samples folder to learn more about this feature. |
| Query enrollments | :heavy_check_mark: | Programmatically query registration states with the service SDK. Please visit the samples folder to learn more about this feature. |
Samples
Within the repository, you can find various types of simple samples that can help you get started.
- Device SDK samples
- Service SDK samples
- Provisioning SDK device samples
- Provisioning SDK service samples
Logging
In order to learn more about logging within this SDK and how to capture its logs, see here.
Contribution, feedback and issues
If you encounter any bugs, have suggestions for new features or if you would like to become an active contributor to this project please follow the instructions provided in the contribution guidelines.
Need support?
- Have a technical question? Ask on Stack Overflow with tag “azure-iot-hub”
- Need Support? Every customer with an active Azure subscription has access to support with guaranteed response time. Consider submitting a ticket and get assistance from Microsoft support team
- Found a bug? Please help us fix it by thoroughly documenting it and filing an issue on GitHub (C, Java, .NET, Node.js, Python).
Here is what you can expect Microsoft Support to be able to help with:
- Client SDKs issues: If you are trying to compile and run the libraries on a supported platform, the Support team will be able to assist with troubleshooting or questions related to compiler issues and communications to and from the IoT Hub. They will also try to assist with questions related to porting to an unsupported platform, but will be limited in how much assistance can be provided. The team will be limited with trouble-shooting the hardware device itself or drivers and or specific properties on that device.
- IoT Hub / Connectivity Issues: Communication from the device client to the Azure IoT Hub service and communication from the Azure IoT Hub service to the client. Or any other issues specifically related to the Azure IoT Hub.
- Portal Issues: Issues related to the portal, that includes access, security, dashboard, devices, Alarms, Usage, Settings and Actions.
- REST/API Issues: Using the IoT Hub REST/APIs that are documented in the documentation.
Read more
- Azure IoT Hub documentation
- Prepare your development environment to use the Azure IoT device SDK for Java
- Setup IoT Hub
- Java SDKs API reference
- Configure TLS Protocol Version and Ciphers
SDK folder structure
/device
Contains Azure IoT Hub client components that provide the raw messaging capabilities of the library. Refer to the API documentation and samples for information on how to use it.
/doc
This folder contains application development guides and device setup instructions.
/iot-e2e-tests
This folder contains end to end tests source code for running on jvm and android.
/vsts
This folder contains scripts to build and run Java SDK provided proper environmental variables are set, as well as azure pipeline resources used for our gating process
Certificates - Important to know
For guidance and important information about certificates, please refer to this blog post from the security team.
Support
The Azure IoT Hub Device Client supported releases is outlined in the following table.
Refer to the Azure IoT Device SDK lifecycle and support for details on the different supported stages.
| Release | Category | End-of-life |
|---|---|---|
| 2.1.5 | Active | - |
| 1.34.3 | Deprecated | 2023-03-30 |
This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.
Microsoft collects performance and usage information which may be used to provide and improve Microsoft products and services and enhance your experience. To learn more, review the privacy statement.