NEQTO Docs
  • Languages iconEnglish
    • 日本語
  • Docs
  • API
  • FAQ

›Integration

Getting Started

  • NEQTO Hello World!
  • Tutorial Step 1. NEQTO Console Setting
  • Tutorial Step 2. Device Settings & Launching Service (NEQTO Bridge)
  • Tutorial Step 2. Device Settings & Launching Service (STM32 Discovery)
  • Tutorial Step 2. Device Settings & Launching Service (SPRESENSE)
  • Tutorial Step 3. Application development using scripts

NEQTO

  • NEQTO Account Registration
  • Sub-accounts
  • API Usage
  • NEQTO CloudSync for GCP
  • NEQTO Engine Firmware List
  • Support Guidelines

NEQTO Console

  • Introduction
  • Fundamentals
  • Administrative Actions
  • Device Management
  • Linux-based Device Management
  • Batch Registration
  • Scripts
  • Actions and Contacts
  • View Data from the Console
  • NEQTO Apps

    • About NEQTO Apps
    • NEQTO Infinitypool
    • NEQTO Insights
    • NEQTO Custodia
    • NEQTO Flow
  • Machine Driver
  • Recommended Browsers
  • Billing Information

SPRESENSE

    Hardware Specifications

    • 01. About Spresense

    Software Specifications

    • 01. Operational Flow
    • 02. Initial Installation
    • 03. Spresense Wi-Fi Initial Setup
    • 04. Spresense LTE-M Initial Setup
    • 05. Debug Log Acquisition
    • 06. System LED Indications
    • 07. Event Messages
    • 08. Updating Firmware

    neqto.js

    • 01. About neqto.js
    • 02. Log
    • 03. Timers
    • 04. HTTP
    • 05. HTTPS
    • 06. MQTT
    • 07. Secure
    • 08. Storage
    • 09. Sleep
    • 10. RTC
    • 11. GPIO
    • 12. UART
    • 13. SPI
    • 14. I2C
    • 15. ADC
    • 16. GNSS
    • 17. Camera
    • 18. Utils
    • 19. nqSpresense
    • 20. nqService
    • 21. nqMqtt
    • 22. nqFOTA
    • 23. nqWiFi
    • 24. nqLte

STM32 Discovery

    Hardware Specifications

    • 01. About STM32 Discovery Kit (B-L4S5I-IOT01A)

    Software Specifications

    • 01. Operational Flow
    • 02. Initial Installation
    • 03. STM32 Discovery Wi-Fi Initial Setup
    • 04. Debug Log Acquisition
    • 05. System LED Indications
    • 06. Event Messages
    • 07. Updating Firmware

    neqto.js

    • 01. About neqto.js
    • 02. Log
    • 03. Timers
    • 04. HTTP
    • 05. HTTPS
    • 06. MQTT
    • 07. Secure
    • 08. Storage
    • 09. Sleep
    • 10. RTC
    • 11. UserSW
    • 12. GPIO
    • 13. UART
    • 14. SPI
    • 15. I2C
    • 16. ADC
    • 18. Utils
    • 19. nqDiscovery
    • 20. nqService
    • 21. nqMqtt
    • 22. nqFOTA
    • 23. nqWiFi

NEQTO Bridge

    Hardware Specifications

    • 01. NEQTO Bridge Module
    • 02. NEQTO Bridge Wi-Fi Module
    • 03. NEQTO Bridge LTE-1 Module
    • 04. NEQTO Bridge LTE-M/NB Module
    • 05. NEQTO Bridge IO Board
    • 06. NEQTO Bridge Digital IO Board
    • 07. NEQTO Bridge Connector Board

    Software Specifications

    • 01. Operational Flow
    • 02. NEQTO Bridge Wi-Fi Module Initial Setup
    • 03. NEQTO Bridge LTE Module Initial Setup
    • 04. Debug Log Acquisition
    • 05. System LED Indications
    • 06. Event Messages
    • 07. Updating Firmware

    neqto.js

    • 01. About neqto.js
    • 02. Log
    • 03. Timers
    • 04. HTTP
    • 05. HTTPS
    • 06. MQTT
    • 07. Secure
    • 08. Storage
    • 09. Sleep
    • 10. RTC
    • 11. UserSW
    • 12. GPIO
    • 13. UART
    • 14. SPI
    • 15. I2C
    • 16. ADC
    • 17. BLE
    • 18. Utils
    • 19. nqBridge
    • 20. nqService
    • 21. nqMqtt
    • 22. nqFOTA
    • 23. nqWiFi
    • 24. nqLte
    • 25. nqLAN
    • 26. nqEx

Linux-based device

    Software Specifications

    • 01. System Requirements
    • 02. Installation
    • 03. Software Configurations
    • 04. Operational Flow
    • 05. Debug Log Acquisition
    • 06. Event Messages
    • 07. Updating Software

    neqto.js

    • 01. About neqto.js
    • 02. Log
    • 03. Timers
    • 04. HTTP
    • 05. HTTPS
    • 06. MQTT
    • 07. Secure
    • 08. Storage
    • 09. RTC
    • 10. UNIXSocket
    • 11. FileSystem
    • 12. SubProcess
    • 13. Utils
    • 14. nqLinux
    • 15. nqService
    • 16. nqMqtt
    • 17. nqFOTA
    • 18. nqLAN

neqto.js Libraries

  • About neqto.js Libraries
  • UART

    • GM65 Barcode Reader
    • SRF Ultrasonic Range Finder - Serial Mode

    I2C

    • HTS221 v2 Temperature and Humidity Sensor
    • LIS2DW12 v2 Accelerometer
    • SRF Ultrasonic Range Finder - I2C Mode
    • [Archive] HTS221 Temperature and Humidity Sensor
    • [Archive] LIS2DW12 Accelerometer

    Utils

    • RTC Alarm Synchronized Scheduler

    Integration

    • AWS S3 v2
    • AWS IoT Core v2
    • Azure IoT v2
    • GCP IoT Core
    • [Archive] AWS S3
    • [Archive] AWS IoT Core

neqto.js Snippets

  • About neqto.js Snippets
  • DataDog
  • Dropbox
  • Google Sheets
  • InfluxDB
  • Oracle Cloud Object Storage
  • Salesforce
  • SAP Cloud Platform Internet of Things
  • Splunk
  • Niagara

Release Notes

  • NEQTO Console Updates
  • NEQTO Firmware (Bridge Wi-Fi/LTE Module) Releases
  • NEQTO Firmware (STM32 Discovery Wi-Fi) Releases
  • NEQTO Firmware (Spresense Wi-Fi/LTE-M) Releases
  • NEQTO Engine for Linux Releases

AWS S3 v2

This library is a built-in class that provides functions to communicate with Amazon Simple Storage Service (Amazon S3).

Library usage requirements
Type Integrations
Name AWS_S3_V2
Version 2020-11-04
Code size used 8.2KB
Resources used HTTPS x 1, Timers x 1

Related Documents

For information on the AWS S3 API used in this library, please refer to the documentation.



Abstracts

Methods()/PropertiesSummary
new AWS_S3()Creates an AWS_S3 instance.

{AWS_S3} Instance

Methods()/PropertiesSummary
.createXAmzHeaders()Converts any AWS API styled params into x-amz-* headers. Ignores bucket and key.
.createHttpHeader()Creates the authentication headers for the given arguments according to the AWS Signature v4 documentation.
.put()Sends a PUT request, outputting the result to the callback function.
.get()Sends a GET request, outputting the result to the passed callback.
.abortRequest()Aborts the currently ongoing request.
.errorsAn array containing the invalid configuration key names. Exists only when an invalid configuration is passed to the constructor.

Details

new AWS_S3(config)

Initializes the AWS_S3 object with the passed configuration.

Configuration

When instantiating the AWS_S3 object, the following configurations are required to be set by the user:

NameTypeDefaultSummary
regionstringMANDATORYRegion to be used when accessing a bucket
accessKeyIdstringMANDATORYAccess key id for authorization from AWS IAM
secretKeystringMANDATORYSecret key for authorization from AWS IAM
bucketstringMANDATORYName of the S3 Bucket to operate on
castringMANDATORYThe root CA to communicate with AWS
timeoutnumber90000The timeout of the AWS_S3 Instance in ms
ver. 2020-07-20+

The configuration must be a JavaScript object, as the following:

var config = {
    region: "<String>",
    accessKeyId: "<String>",
    secretKey: "<String>",
    bucket: "<String>",
    ca: "<String>"
};

Once the configuration is set, it can be passed to AWS_S3 during instance creation. If any invalid values are passed, the result from setConfig is stored in an errors property, and should be handled appropriately.

var s3 = new AWS_S3(config);
if ('errors' in s3) {
    // TODO: handle errors
}

Setter Methods

After creating the AWS_S3 object, each of the aforementioned configurations may be changed by its corresponding setter, with a passed in value of String type. The values for accessKeyId and secretKey may be retrieved from AWS IAM.

SetterSummary
.setRegion(value: string)Set the region for this AWS_S3 instance.
.setBucket(value: string)Set the bucket for this AWS_S3 instance.
.setAccessKeyId(value: string)Set the Access Key ID for this AWS_S3 instance, used for authentication.
.setSecretKey(value: string)Set the Secret Key for this AWS_S3 instance, used for authentication.
.setRootCA(value: string)Set the root CA for this AWS_S3 instance, used for connecting to AWS.
The suggested value can be seen below.
.setRequestTimeout(value: Number)Set the timeout for this AWS_S3 instance.
ver. 2020-07-20+
`

The configuration setters can also be chained, if they were all successful. Each setter returns an Error when given an invalid value, instead of an AWS_S3 instance for method chaining.

.setConfig(config)

The setConfig function can be used to set or change multiple config options at the same time, and takes in a typical JavaScript object of key:value pairs as an argument.

s3.setConfig({
    region: "value",
    accessKeyId: "value",
    secretKey: "value",
    bucket: "value",
    ca: "value"
});

Instance Methods

.createXAmzHeaders(params)

Creates the x-amz-* headers from the passed params.

NameTypeDefaultSummary
paramsobjectMANDATORYThe AWS API params object to convert into x-amz-* headers.
returnobject-params converted into x-amz-* headers if they exist as params in the API docs.

.createHttpHeader(host,path,method,bodyToHash,additionalHeaders)

Creates the authentication headers for the given arguments according to the AWS Signature v4 documentation.
This method can be utilized when directly communicating using an HTTP object.

NameTypeDefaultSummary
hoststringMANDATORYHTTP host
pathstringMANDATORYHTTP path
methodstringMANDATORYHTTP Method
bodyToHashstringMANDATORYHTTP Body; null to pass UNSIGNED_PAYLOAD instead.
additionalHeadersobjectMANDATORYAn Object with additional x-amz-* headers for signing
returnobject-{ Authorization: [auth], x-amz-content-sha256: [contenthash], x-amz-date: [timestamp]}

.put(path,userHeaders,body,callback)

Sends a PUT request, passing the result to the callback function. This function uses the AWS S3 API: https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html

NameTypeDefaultSummary
pathstringMANDATORYThe path to the desired resource. The path is always appended to the host [bucket].s3.amazonaws.com.
userHeadersobjectMANDATORYAn Object with a "Content-Length" header (mandatory) and any additional HTTP/2 or x-amz-* headers.
bodyfunctionMANDATORYCallback to retrieve the contents of the object. Should return data in up to 4KB [string/ArrayBuffer] chunks until exhausted, then return null.
callback(err, resp)functionMANDATORYThe user’s callback function, to handle the response. Will pass an Error as err and a Response as resp.

.get(path,callback)

Sends a GET request, passing the result to the callback function. This function uses the AWS S3 API: https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html

NameTypeDefaultSummary
pathstringMANDATORYThe path to the desired resource. The path is always appended to the host [bucket].s3.amazonaws.com.
callback(err, resp)functionMANDATORYThe user’s callback function, to handle the response. Will pass an Error as err and a Response as resp.

.abortRequest()

Aborts the currently ongoing request.

NameTypeDefaultSummary
returnundefined--

Response Object

This library uses an object called a Response to handle AWS server responses. Responses are always in the following format:

{
    statusCode: <Number>,
    statusMessage: <String>,
    body: <ArrayBuffer> or <String>
}

More details on statusCode and statusMessage can be seen in the HTTPs documentation for the appropriate device (NEQTO Bridge | Spresense).

body is the body data from the HTTP response.

Errors

In this library, Errors are returned in two ways: as return values from the setters, and passed as err into the callback function for the HTTP methods.

Errors raised outside of an HTTP request take the following form:

{
    name: <String>,
    message: <String>
}

Errors raised from an HTTP request take the following form:

{
    errCode: <Number>
}

Errors which detect invalid configurations, such as a missing Content-Length header, will have a message property; Errors which are raised from the HTTP/S layer will not have this property. Errors raised in this way have more information available regarding their errCode parameter in the NEQTO Bridge and Spresense neqto.js documentation.

The following is an example of how to handle the various forms of Errors:

var invalidConfig = {
    badKey: "badValue"
};
var s3 = new AWS_S3(invalidConfig);
// s3 now contains an array of errors
if (Array.isArray(s3)) {
    //handle config errors
} else {
    //s3 is good in this block
    var callback = function (err, data) {
        if (err) {
            // handle errors
            JSON.stringify(err)
        } else {
            // handle data
        }
    }
    s3.get('/example.txt', callback);
}

Usage Examples

Click here to learn how to get the CA that can be used in the config option.

Verify that the root CA is appropriate for the target S3 endpoint.

var rootCa = '-----BEGIN CERTIFICATE-----\n...<CA>...\n-----END CERTIFICATE-----';

Example 1: Put an Object to S3

// IMPORTED LIBRARIES
// - AWS_S3_V2

// Logging setup
log.setLevel(0,2); //-1:NONE 0:ERROR 1:WARNING 2:DEBUG 3:TRACE, 0:DISABLE 1:LOG 2:CONSOLE 3:BOTH
log.printLevel(2); //0:DISABLE 1:LOG 2:CONSOLE 3:BOTH

// Set config
var config = {
    region: "<String>",
    accessKeyId: "<String>",
    secretKey: "<String>",
    bucket: "<String>",
    ca: awsS3Ca
};

var callback = function (err, data) {
    if (err) {
        print("Error!", JSON.stringify(err));
    } else {
        print(data.statusCode, data.statusMessage);
        print(data.body);
    }
}

var s3 = new AWS_S3(config);
if ('errors' in s3) {
    // TODO: handle errors
    throw 'Invalid configuration'
}


/**
 * Create a large buffer (representing data generated from sensors)
 * and send it to AWS S3 with a custom tag and ACL parameter.
 */

 var path = '/path/to/resource.txt';
 var dataSize = 12 * 1024;
 var params = {
     "Tagging": "example=tag", // Requires the s3:PutObjectTagging permission
     "ACL": "bucket-owner-full-control", // Requires the s3:PutObjectAcl permission
     "ContentLength": dataSize.toString()
 }

 var buffer = new ArrayBuffer(dataSize);
 var bufferView = new Uint8Array(buffer);
 for (var b = 0; b < bufferView.length; b++) {
     bufferView[b] = (b % 255); // Fill it with arbitrary data
 }

 var putObject = function(path, params, body, callback) {
     var headers = s3.createXAmzHeaders(params);
     var MAX_CHUNK_SIZE = 4 * 1024;
     var bodyIndex = 0;
     var getNextChunk = function() {
         var ret;
         if (bodyIndex >= dataSize) {
             ret = null;
         } else {
             ret = body.slice(bodyIndex, bodyIndex + MAX_CHUNK_SIZE);
         }
         if (ret) {
             bodyIndex += ret.length || ret.byteLength;
         }
         return ret;
     }
     s3.put(path, headers, getNextChunk, callback);
 }

 putObject(path, params, buffer, callback);

Example 2: Put Data from Storage to S3

// IMPORTED LIBRARIES
// - AWS_S3_V2

// Logging setup
log.setLevel(0,2); //-1:NONE 0:ERROR 1:WARNING 2:DEBUG 3:TRACE, 0:DISABLE 1:LOG 2:CONSOLE 3:BOTH
log.printLevel(2); //0:DISABLE 1:LOG 2:CONSOLE 3:BOTH

// Set config
var config = {
    region: "<String>",
    accessKeyId: "<String>",
    secretKey: "<String>",
    bucket: "<String>",
    ca: awsS3Ca
};

var callback = function (err, data) {
    if (err) {
        print("Error!", JSON.stringify(err));
    } else {
        print(data.statusCode, data.statusMessage);
        print(data.body);
    }
}

var s3 = new AWS_S3(config);
if ('errors' in s3) {
    // TODO: handle errors
    throw 'Invalid configuration'
}

/**
 * Store data on the filesystem, then send that stored data.
 */

var path = "/path/to/storage.txt";
var dataSize = 16384;
var params = {
    "ContentLength": dataSize.toString(),
}

var store = storage.open();
var head = "HEADER:";

// Create a test data string and save it to memory
var s = "";
// Up to 4KB of data, to be compatible with put()
while(s.length < 1024) {
    s += "testdata";
}
for (var i = 0; i < 24; i++) {
    store.writeFrame(head, s);
}

// If there was an error during memory save, recover it.
if (!store.readFrame(head, 0)) {
    var ret = store.recoverFrame(head);
}

var putStringFromStorage = function (strStore) {
    var headers = s3.createXAmzHeaders(params);
    var getData;
    if (strStore) {
        if (strStore.getReadableSize() < dataSize) {
            return null;
        }
        if (head) {
            // Get total amount of data in frames with this head
            var frames = strStore.searchAllFrame(head, 0);
            if (frames < dataSize) { // not enough stored data
                return null;
            }
            // Get total number of frames with this head
            frames = strStore.searchAllFrame(head, 1);
            var frameIndex = -1;
            var frameDataCollectedSize = 0;
            var getData = function() {
                if (frameIndex++ < frames && frameDataCollectedSize < dataSize) {
                    var ret = strStore.searchFrame(head, frameIndex);
                    frameDataCollectedSize += ret.length;
                    return ret;
                } else {
                    return null;
                }
            }
        }
    }
    s3.put(path, headers, getData, callback);
}
putStringFromStorage(store);


Example 3: Put Custom Data to S3

// IMPORTED LIBRARIES
// - AWS_S3_V2

// Logging setup
log.setLevel(0,2); //-1:NONE 0:ERROR 1:WARNING 2:DEBUG 3:TRACE, 0:DISABLE 1:LOG 2:CONSOLE 3:BOTH
log.printLevel(2); //0:DISABLE 1:LOG 2:CONSOLE 3:BOTH

// Set config
var config = {
    region: "<String>",
    accessKeyId: "<String>",
    secretKey: "<String>",
    bucket: "<String>",
    ca: awsS3Ca
};

var callback = function (err, data) {
    if (err) {
        print("Error!", JSON.stringify(err));
    } else {
        print(data.statusCode, data.statusMessage);
        print(data.body);
    }
}

var s3 = new AWS_S3(config);
if ('errors' in s3) {
    // TODO: handle errors
    throw 'Invalid configuration'
}

/**
 * Send data to S3 using a custom getData method.
 */

 var path = "/path/to/custom.txt";
 var dataSize = 256;
 var params = {
     "Content-Length": dataSize.toString()
 }

 var send = false;
 var getData = function () { // Must return String, ArrayBuffer, or null.
     if (send) {
         return null;
     } else {
         send = true;
         var i = 0;
         var ret = "";
         while (i++ < dataSize) {
             ret += String.fromCharCode((i % 95) + 32); // ASCII table
         }
         return ret;
     }
 }

 s3.put(path, params, getData, callback);
The company names and product names mentioned above are registered trademarks or trademarks of their respective companies.

Updated: 2023-01-20
← RTC Alarm Synchronized SchedulerAWS IoT Core v2 →
  • Abstracts
    • {AWS_S3} Instance
  • Details
    • new AWS_S3(config)
    • Setter Methods
    • Instance Methods
    • Response Object
    • Errors
  • Usage Examples
    • Example 1: Put an Object to S3
    • Example 2: Put Data from Storage to S3
    • Example 3: Put Custom Data to S3
AboutNewsProductsFAQPrivacy Policy}
NEQTO Console
IntroductionFundamentalsAdministrative ActionsDevice Management NEQTO Apps
NEQTO Bridge
NEQTO Bridge ModuleNEQTO Bridge Wi-Fi ModuleNEQTO Bridge LTE-1 ModuleError Logging Event Messages
API Documentation
API UsageGlobal APIRegional APIAPI Terms of Service
Jigsaw, Inc.
© 2023 JIG-SAW INC.