Skip to content

Commit 1a4a1af

Browse files
xiazhveraxiazhvera
authored
Merge branch 'main' into file_validation
2 parents f2872e0 + 4234388 commit 1a4a1af

File tree

4 files changed

+155
-273
lines changed

4 files changed

+155
-273
lines changed

‎README.md‎

Lines changed: 82 additions & 51 deletions
Original file line numberDiff line numberDiff line change
@@ -1,88 +1,119 @@
11
# AWS IoT Device SDK for JavaScript v2
22

3-
This document provides information about the AWS IoT device SDK for Javascript V2. This SDK is built on the [AWS Common Runtime](https://docs.aws.amazon.com/sdkref/latest/guide/common-runtime.html)
3+
The AWS IoT Device SDK for JavaScript v2 connects your JavaScript applications and devices to the AWS IoT platform. It handles the complexities of secure communication, authentication, and device management so you can focus on your IoT solution. The SDK makes it easy to use AWS IoT services like Device Shadows, Jobs, and Fleet Provisioning.
44

5-
*__Jump To:__*
5+
**Supported Platforms**: Linux, Windows 11+, macOS 14+
6+
7+
> **Note**: The SDK is known to work on older platform versions, but we only guarantee compatibility for the platforms listed above.
8+
9+
*__Topics:__*
10+
* [Features](#features)
611
* [Installation](#installation)
7-
* [Samples](https://github.com/aws/aws-iot-device-sdk-js-v2/tree/main/samples)
8-
* [Mac-Only TLS Behavior](#mac-only-tls-behavior)
9-
* [Getting Help](#getting-help)
10-
* [FAQ](https://github.com/aws/aws-iot-device-sdk-js-v2/blob/main/documents/FAQ.md)
11-
* [API Docs](https://aws.github.io/aws-iot-device-sdk-js-v2/)
12+
* [Minimum Requirements](#minimum-requirements)
13+
* [Installing from npm](#installing-from-npm)
14+
* [Getting Started](#getting-started)
15+
* [Samples](samples)
1216
* [MQTT5 User Guide](https://github.com/awslabs/aws-crt-nodejs/blob/main/MQTT5-UserGuide.md)
13-
* [Migration Guide from the AWS IoT SDK for JavaScript v1](./documents/MIGRATION_GUIDE.md)
17+
* [Getting Help](#getting-help)
18+
* [Resources](#resources)
19+
20+
## Features
21+
22+
The primary purpose of the AWS IoT Device SDK for JavaScript v2 is to simplify the process of connecting devices to AWS IoT Core and interacting with AWS IoT services on various platforms. The SDK provides:
23+
24+
* Integrated service clients for AWS IoT Core services
25+
* Secure device connections to AWS IoT Core using MQTT protocol including MQTT 5.0
26+
* Support for [multiple authentication methods and connection types](https://github.com/awslabs/aws-crt-nodejs/blob/main/MQTT5-UserGuide.md#how-to-create-an-mqtt5-client-based-on-desired-connection-method)
27+
28+
#### Supported AWS IoT Core services
29+
30+
* The [AWS IoT Device Shadow](https://docs.aws.amazon.com/iot/latest/developerguide/iot-device-shadows.html) service manages device state information in the cloud.
31+
* The [AWS IoT Jobs](https://docs.aws.amazon.com/iot/latest/developerguide/iot-jobs.html) service sends remote operations to connected devices.
32+
* The [AWS IoT fleet provisioning](https://docs.aws.amazon.com/iot/latest/developerguide/provision-wo-cert.html) service generates and delivers device certificates automatically.
1433

1534
## Installation
1635

36+
The recommended way to use the AWS IoT Device SDK for JavaScript v2 in your project is to install it from npm.
37+
1738
### Minimum Requirements
1839

19-
For use with Node, the following are required:
20-
* Node v14+
21-
* Run `node -v` to check Node version.
22-
* CMake 3.1+
40+
To develop applications with the AWS IoT Device SDK for JavaScript v2, you need:
41+
42+
* Node.js v14+
43+
* Run `node -v` to check Node version
44+
45+
See [detailed setup instructions](./documents/PREREQUISITES.md) for more information.
46+
47+
### Installing from npm
2348

24-
[Step-by-step instructions](https://github.com/aws/aws-iot-device-sdk-js-v2/blob/main/documents/PREREQUISITES.md)
49+
Navigate to your JavaScript project directory and install the SDK:
2550

26-
### Build SDK in existing project with NPM
27-
``` sh
28-
# Navigate to the Javascript project you want to add the
29-
# Javascript V2 SDK to.
30-
cd <your javascript project here>
31-
# Install the V2 SDK.
51+
```bash
52+
cd <your-javascript-project>
3253
npm install aws-iot-device-sdk-v2
33-
# Now you can use the Javascript V2 SDK in your project.
3454
```
3555

36-
### Build the V2 SDK from source
56+
### Building from source
3757

38-
``` sh
39-
# Create a workspace directory to hold all the SDK files.
40-
mkdir sdk-workspace
41-
cd sdk-workspace
58+
See the [Development Guide](./documents/DEVELOPING.md) for detailed instructions on building from source and using local builds.
4259

43-
# Clone the repository to access the samples.
44-
git clone https://github.com/aws/aws-iot-device-sdk-js-v2.git
60+
## Getting Started
4561

46-
# Install the SDK.
47-
cd aws-iot-device-sdk-js-v2
48-
npm install
62+
To get started with the AWS IoT Device SDK for JavaScript v2:
4963

50-
# Then you can run the samples following the instructions in the samples README.
51-
```
64+
1. **Install the SDK** - See the [Installation](#installation) section for installation details
65+
66+
2. **Choose your connection method** - The SDK supports multiple authentication methods including X.509 certificates, AWS credentials, and custom authentication. [MQTT5 User Guide connection section](https://github.com/awslabs/aws-crt-nodejs/blob/main/MQTT5-UserGuide.md#connecting-to-aws-iot-core) provides more guidance
67+
68+
3. **Follow a complete example** - Check out the [samples](samples) directory
69+
70+
4. **Learn MQTT5 features** - For advanced usage and configuration options, see the [MQTT5 User Guide](https://github.com/awslabs/aws-crt-nodejs/blob/main/MQTT5-UserGuide.md)
71+
72+
The samples provide ready-to-run code with detailed setup instructions for each authentication method and use case.
5273

5374
## Samples
5475

55-
[Samples README](https://github.com/aws/aws-iot-device-sdk-js-v2/blob/main/samples/README.md)
76+
Check out the [samples](samples) directory for working code examples that demonstrate:
77+
- [Basic MQTT connection and messaging](./samples/node/pub_sub_mqtt5)
78+
- [AWS IoT Device Shadow operations](./samples/node/service_clients/shadow)
79+
- [AWS IoT Jobs](./samples/node/service_clients/jobs)
80+
- [AWS IoT Fleet provisioning](./samples/node/service_clients/fleet_provisioning)
81+
82+
The samples provide ready-to-run code with detailed setup instructions for each authentication method and use case.
83+
84+
## Getting Help
5685

57-
### Mac-Only TLS Behavior
86+
The best way to interact with our team is through GitHub.
87+
* Open [discussion](https://github.com/aws/aws-iot-device-sdk-js-v2/discussions): Share ideas and solutions with the SDK community
88+
* Search [issues](https://github.com/aws/aws-iot-device-sdk-js-v2/issues): Find created issues for answers based on a topic
89+
* Create an [issue](https://github.com/aws/aws-iot-device-sdk-js-v2/issues/new/choose): New feature request or file a bug
90+
91+
If you have a support plan with [AWS Support](https://aws.amazon.com/premiumsupport/), you can also create a new support case.
92+
93+
#### Mac-Only TLS Behavior
5894

5995
Please note that on Mac, once a private key is used with a certificate, that certificate-key pair is imported into the Mac Keychain. All subsequent uses of that certificate will use the stored private key and ignore anything passed in programmatically. Beginning in v1.7.3, when a stored private key from the Keychain is used, the following will be logged at the "info" log level:
6096

6197
```
62-
static: certificate has an existing certificate-key pair that was previously imported into the Keychain. Using key from Keychain instead of the one provided.
98+
static: certificate has an existing certificate-key pair that was previously imported into the Keychain.
99+
Using key from Keychain instead of the one provided.
63100
```
64101

65-
## Getting Help
66-
67-
The best way to interact with our team is through GitHub. You can open a [discussion](https://github.com/aws/aws-iot-device-sdk-js-v2/discussions) for guidance questions or an [issue](https://github.com/aws/aws-iot-device-sdk-js-v2/issues/new/choose) for bug reports, or feature requests. You may also find help on community resources such as [StackOverFlow](https://stackoverflow.com/questions/tagged/aws-iot) with the tag [#aws-iot](https://stackoverflow.com/questions/tagged/aws-iot) or if you have a support plan with [AWS Support](https://aws.amazon.com/premiumsupport/), you can also create a new support case.
102+
## Resources
68103

69-
Please make sure to check out our resources too before opening an issue:
104+
Check out our resources for additional guidance too before opening an issue:
70105

71-
* [FAQ](https://github.com/aws/aws-iot-device-sdk-js-v2/blob/main/documents/FAQ.md)
72-
* [API Docs](https://aws.github.io/aws-iot-device-sdk-js-v2/)
73-
* [IoT Guide](https://docs.aws.amazon.com/iot/latest/developerguide/what-is-aws-iot.html) ([source](https://github.com/awsdocs/aws-iot-docs))
106+
* [FAQ](./documents/FAQ.md)
107+
* [AWS IoT Core Developer Guide](https://docs.aws.amazon.com/iot/latest/developerguide/what-is-aws-iot.html)
74108
* [MQTT5 User Guide](https://github.com/awslabs/aws-crt-nodejs/blob/main/MQTT5-UserGuide.md)
75-
* Check for similar [Issues](https://github.com/aws/aws-iot-device-sdk-js-v2/issues)
109+
* [API Docs](https://aws.github.io/aws-iot-device-sdk-js-v2/)
76110
* [AWS IoT Core Documentation](https://docs.aws.amazon.com/iot/)
77-
* [Dev Blog](https://aws.amazon.com/blogs/?awsf.blog-master-iot=category-internet-of-things%23amazon-freertos%7Ccategory-internet-of-things%23aws-greengrass%7Ccategory-internet-of-things%23aws-iot-analytics%7Ccategory-internet-of-things%23aws-iot-button%7Ccategory-internet-of-things%23aws-iot-device-defender%7Ccategory-internet-of-things%23aws-iot-device-management%7Ccategory-internet-of-things%23aws-iot-platform)
78-
* Integration with AWS IoT Services such as
79-
[Device Shadow](https://docs.aws.amazon.com/iot/latest/developerguide/iot-device-shadows.html)
80-
and [Jobs](https://docs.aws.amazon.com/iot/latest/developerguide/iot-jobs.html)
81-
is provided by code that been generated from a model of the service.
82-
* [Contributions Guidelines](https://github.com/aws/aws-iot-device-sdk-js-v2/blob/main/documents/CONTRIBUTING.md)
111+
* [Dev Blog](https://aws.amazon.com/blogs/iot/category/internet-of-things/)
112+
* [Migration Guide from the AWS IoT SDK for JavaScript v1](./documents/MIGRATION_GUIDE.md)
113+
* [Contributions Guidelines](./documents/CONTRIBUTING.md)
83114

84115
## License
85116

86-
This library is licensed under the [Apache 2.0 License](https://github.com/aws/aws-iot-device-sdk-js-v2/blob/main/documents/LICENSE).
117+
This library is licensed under the [Apache 2.0 License](./documents/LICENSE).
87118

88-
Latest released version: v1.23.0
119+
Latest released version: v1.23.1

‎documents/DEVELOPING.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Development Guide
2+
3+
This document provides instructions for building and developing with the AWS IoT Device SDK for JavaScript v2.
4+
5+
## Building from source
6+
7+
```bash
8+
# Create a workspace directory to hold all the SDK files
9+
mkdir sdk-workspace
10+
cd sdk-workspace
11+
12+
# Clone the repository
13+
git clone https://github.com/aws/aws-iot-device-sdk-js-v2.git
14+
cd aws-iot-device-sdk-js-v2
15+
16+
# Install dependencies
17+
npm install
18+
```
19+
20+
The SDK version will be `1.0.0-dev`, so just specify this version in your application config. Alternatively, you can change the version in the [package.json](../package.json#L3) file.

‎documents/FAQ.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@
33
*__Jump To:__*
44
* [Where should I start](#where-should-i-start)
55
* [How do I enable logging](#how-do-i-enable-logging)
6+
* [How do I get more information from an error code?](#how-do-i-get-more-information-from-an-error-code)
67
* [I keep getting AWS_ERROR_MQTT_UNEXPECTED_HANGUP](#i-keep-getting-aws_error_mqtt_unexpected_hangup)
78
* [How do debug in VSCode?](#how-do-debug-in-vscode)
89
* [What certificates do I need?](#what-certificates-do-i-need)
@@ -23,6 +24,20 @@ io.enable_logging(level);
2324
```
2425
You can also enable [CloudWatch logging](https://docs.aws.amazon.com/iot/latest/developerguide/cloud-watch-logs.html) for IoT which will provide you with additional information that is not available on the client side sdk.
2526

27+
### How do I get more information from an error code?
28+
29+
When you encounter an error code, you can get the human-readable error message using the `error_code_to_string()` function:
30+
31+
``` js
32+
import {io} from "aws-iot-device-sdk-v2";
33+
34+
// Convert error code to readable message
35+
const errorMessage = io.error_code_to_string(errorCode);
36+
console.log(`Error: ${errorMessage}`);
37+
```
38+
39+
This will convert numeric error codes into descriptive error messages that can help you understand what went wrong.
40+
2641
### I keep getting AWS_ERROR_MQTT_UNEXPECTED_HANGUP
2742

2843
This could be many different things but it most likely is a policy issue. Start with using a super permissive IAM policy called AWSIOTFullAccess which looks like this:

0 commit comments

Comments
 (0)