Skip to content

Commit 995a362

Browse files
sbSteveKsbSteveK
committed
main samples README
1 parent d9fde89 commit 995a362

File tree

1 file changed

+84
-43
lines changed

1 file changed

+84
-43
lines changed

‎samples/README.md‎

Lines changed: 84 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -1,62 +1,103 @@
11
# Sample Applications for the AWS IoT Device SDK for Java v2
2+
This directory contains sample applications for [aws-iot-device-sdk-java-v2](../README.md)
23

3-
## MQTT5 Samples
4-
#### MQTT5 is the recommended MQTT Client. It has many benefits over MQTT311 outlined in the [MQTT5 User Guide](../documents/MQTT5_Userguide.md)
5-
* [MQTT5 PubSub](./Mqtt5/PubSub/README.md)
6-
* [Direct MQTT with X509-based Mutual TLS Method](./Mqtt5/PubSub/README.md#direct-mqtt-with-x509-based-mutual-tls-method)
7-
* [Direct MQTT with Custom Authorizer Method](./Mqtt5/PubSub/README.md#direct-mqtt-with-custom-authorizer-method)
8-
* [Direct MQTT with PKCS11 Method](./Mqtt5/PubSub/README.md#direct-mqtt-with-pkcs11-method)
9-
* [Direct MQTT with PKCS12 Method](./Mqtt5/PubSub/README.md#direct-mqtt-with-pkcs12-method)
10-
* [Direct MQTT with Custom Key Operations Method](./Mqtt5/PubSub/README.md#direct-mqtt-with-custom-key-operation-method)
11-
* [Direct MQTT with Windows Certificate Store Method](./Mqtt5/PubSub/README.md#direct-mqtt-with-windows-certificate-store-method)
12-
* [Direct MQTT with Java Keystore Method](./Mqtt5/PubSub/README.md#direct-mqtt-with-java-keystore-method)
13-
* [Websocket Connection with Sigv4 Authentication Method](./Mqtt5/PubSub/README.md#websocket-connection-with-sigv4-authentication-method)
14-
* [Websocket Connection with Cognito Authentication Method](./Mqtt5/PubSub/README.md#websocket-connection-with-cognito-authentication-method)
15-
* [MQTT5 Shared Subscription](./Mqtt5/SharedSubscription/README.md)
16-
## Other Samples
17-
* [Shadow](./ShadowSandbox/README.md)
18-
* [Jobs](./JobsSandbox/README.md)
19-
* [Commands](./CommandsSandbox/README.md)
20-
* [Fleet Provisioning](./Provisioning/Basic/README.md)
21-
* [Fleet Provisioning with CSR](./Provisioning/Csr/README.md)
22-
* [Android Sample](./Android/README.md)
23-
* [Greengrass Discovery](./Greengrass/README.md)
24-
* [Greengrass IPC](./GreengrassIPC/README.md)
25-
26-
### Note
27-
28-
Note that **all samples will show their options by passing in `--help`**. For example:
4+
### Table of Contents
5+
* [Samples](#samples)
6+
* [MQTT5 Client Samples](#mqtt5-client-samples)
7+
* [Service Client Samples](#service-client-samples)
8+
* [Greengrass Samples](#greengrass-samples)
9+
* [Instructions](#instructions)
10+
* [Sample Help](#sample-help)
11+
* [Enable Logging](#enable-logging)
2912

30-
```sh
31-
mvn compile exec:java -pl samples/BasicPubSub -Dexec.mainClass=pubsub.PubSub -Dexec.args='--help'
32-
```
13+
## Samples
14+
### MQTT5 Client Samples
15+
##### MQTT5 is the recommended MQTT Client. Additional infomration and usage instructions can be found in the [MQTT5 User Guide](../documents/MQTT5_Userguide.md). The samples below will create an MQTT5 client, connect using the selected method, subscribe to a topic, publish to the topic, and then disconnect.
16+
| MQTT5 Client Sample | Description |
17+
|--------|-------------|
18+
| [X509-based mutual TLS](./mqtt/mqtt5x509/README.md) | Demonstrates connecting to AWS IoT Core using X.509 certificates and private keys.
19+
| [Websockets with Sigv4 authentication](./mqtt/mqtt5awswebsocket/README.md) | Shows how to authenticate over websockets using AWS Signature Version 4 credentials. |
20+
| [AWS Signed Custom Authorizer Lambda Function](./mqtt/mqtt5customauthsigned/README.md) | Connecting with a signed Lambda-backed custom authorizer.
21+
| [AWS Unsigned Custom Authorizer Lambda Function](./mqtt/mqtt5customauthunsigned/README.md) | Connecting with an unsigned Lambda-backed custom authorizer.
22+
| [PKCS11](./mqtt/mqtt5pkcs11/README.md) | Demonstrates connecting using a hardware security module (HSM) or smartcard with PKCS#11. |
23+
| [Other Connection Methods](../documents/MQTT5_Userguide.md#how-to-create-an-mqtt5-client-based-on-desired-connection-method) | More connection methods are available for review in the MQTT5 Userguide
3324

34-
Additionally, you can enable logging in all samples. To enable logging in the samples, you will need to set the following system properties when running the samples:
25+
### Service Client Samples
26+
##### AWS offers a number of IoT related services using MQTT. The samples below demonstrate how to use the service clients provided by the SDK to interact with those services.
27+
| Service Client Sample | Description |
28+
|--------|-------------|
29+
| [Shadow](./serviceclients/shadowv2/README.md) | Manage and sync device state using the IoT Device Shadow service. |
30+
| [Basic Fleet Provisioning](./serviceclients/provisioning/basic/README.md) | Provision a device using the Fleet Provisioning template. |
31+
| [CSR Fleet Provisioning](./serviceclients/provisioning/csr/README.md) | Demonstrates CSR-based device certificate provisioning. |
32+
| [Shadow Sandbox](./serviceclients/shadowsandbox/README.md) | Sandbox sample to manage and sync device state using the IoT Device Shadow service. |
33+
| [Jobs Sandbox](./serviceclients/jobssandbox/README.md) | Sandbox sample to receive and execute remote operations sent from the Jobs service. |
34+
| [Commands Sandbox](./serviceclients/provisioning/csr/README.md) | Sandbox sample to demonstrante Commands service. |
3535

36-
```sh
37-
-Daws.crt.debugnative=true
38-
-Daws.crt.log.destination=File
39-
-Daws.crt.log.level=Trace
40-
-Daws.crt.log.filename=<path and filename>
41-
```
36+
### Greengrass Samples
37+
##### Samples that interact with [AWS Greengrass](https://aws.amazon.com/greengrass/).
38+
| Greengrass Sample | Description |
39+
|--------|-------------|
40+
| [Greengrass Discovery](./greengrass/discovery/README.md) | Discover and connect to a local Greengrass core. |
41+
| [Greengrass IPC](./greengrass/greengrassipc/README.md) | Demonstrates Inter-Process Communication (IPC) with Greengrass components. |
4242

43-
* `aws.crt.debugnative`: Whether to debug native (C/C++) code. Can be either `true` or `false`.
44-
* `aws.crt.log.destination`: Where the logs are outputted to. Can be `File`, `Stdout` or `Stderr`. Defaults to `Stderr`.
45-
* `aws.crt.log.level`: The level of logging shown. Can be `Trace`, `Debug`, `Info`, `Warn`, `Error`, `Fatal`, or `None`. Defaults to `Warn`.
46-
* `aws.crt.log.filename`: The path to save the log file. Only needed if `aws.crt.log.destination` is set to `File`.
43+
### Instructions
4744

48-
For example, to run `PubSub` with logging you could use the following:
45+
First, install `aws-iot-device-sdk-java-v2`. Installation instructions for the SDK are [Provided Here](../README.md#installation).
46+
47+
Each sample's README contains prerequisites, arguments, and detailed instructions. For example, the [MQTT X509 Sample README](./mqtt/mqtt5x509/README.md) instructs to run the sample with the following command:
4948

5049
```sh
51-
mvn compile exec:java -pl samples/Mqtt5/PubSub -Daws.crt.debugnative=true -Daws.crt.log.level=Debug -Daws.crt.log.destionation=Stdout -Dexec.mainClass=pubsub.PubSub -Dexec.args='--endpoint <endpoint> --cert <path to cert> --key <path to key> --ca_file <path to ca file>'
50+
mvn compile exec:java \
51+
-pl samples/mqtt/mqtt5x509 \
52+
-Dexec.args=" \
53+
--endpoint <ENDPOINT> \
54+
--cert <PATH TO CERTIFICATE FILE> \
55+
--key <PATH TO PRIVATE KEY FILE>"
5256
```
5357

5458
### Running Samples with latest SDK release
5559

5660
If you want to run a sample using the latest release of the SDK, instead of compiled from source, you need to use the `latest-release` profile. For example:
5761

5862
```sh
59-
mvn -P latest-release compile exec:java -pl samples/Mqtt5/PubSub -Dexec.mainClass=mqtt5.pubsub.PubSub -Dexec.args='--endpoint <endpoint> --cert <path to certificate> --key <path to private key> --ca_file <path to root CA>'
63+
mvn -P latest-release compile exec:java \
64+
-pl samples/mqtt/mqtt5x509 \
65+
-Dexec.args=" \
66+
--endpoint <ENDPOINT> \
67+
--cert <PATH TO CERTIFICATE FILE> \
68+
--key <PATH TO PRIVATE KEY FILE>"
6069
```
6170

6271
This will run the sample using the latest released version of the SDK rather than the version compiled from source. If you are wanting to try the samples without first compiling the SDK, then make sure to add `-P latest-release` and to have Maven download the Java V2 SDK. **This works for all samples in the Java V2 SDK.**
72+
73+
### Sample Help
74+
75+
All samples will show their options and arguments by passing in `--help`. For example:
76+
``` sh
77+
mvn compile exec:java \
78+
-pl samples/mqtt/mqtt5x509 \
79+
-Dexec.args=" \
80+
--help"
81+
```
82+
83+
Will result in the following print output:
84+
```
85+
MQTT5 X509 Sample (mTLS)
86+
87+
Required:
88+
--endpoint <ENDPOINT> IoT endpoint hostname
89+
--cert <CERTIFICATE> Path to certificate file (PEM)
90+
--key <PRIVATE_KEY> Path to private key file (PEM)
91+
92+
Optional:
93+
--client_id <CLIENT_ID> MQTT client ID (default: generated)
94+
--topic <TOPIC> Topic to use (default: test/topic)
95+
--message <MESSAGE> Message payload (default: "Hello from mqtt5 sample")
96+
--count <N> Messages to publish (0 = infinite, default: 5)
97+
```
98+
99+
The sample will not run without the required arguments.
100+
101+
### Enable Logging
102+
103+
Instructions to enable logging are available in the [FAQ](../documents/FAQ.md) under [How do I enable logging](../documents/FAQ.md#how-do-i-enable-logging).

0 commit comments

Comments
 (0)