Meshblu HTTP API Client
raw JSON → 10.2.0 verified Thu Apr 23 auth: no javascript maintenance
meshblu-http is a Node.js client library for interacting with the Meshblu HTTP API, primarily associated with the Octoblu IoT platform. It provides a programmatic interface for common operations such as device registration, authentication, sending and receiving messages, and managing subscriptions and webhooks. The library is currently at version 10.2.0, with a history of minor and patch releases addressing features like `bearerToken` support and improved subscription management. While the broader Meshblu ecosystem has evolved significantly since 2017 into a microservices architecture (e.g., `meshblu-core-*` components), this client library largely targets the HTTP API of the original Meshblu 1.0 or compatible services. Its API predominantly uses a callback-based pattern, reflecting its origins as a CoffeeScript-driven project. It serves as a high-level abstraction for interacting with IoT devices and services connected to the Meshblu platform via HTTP.
Common errors
error Failed to register device: Unauthorized ↓
cause Attempting to register or perform other operations with invalid or missing `uuid` and `token` credentials, or connecting to a Meshblu instance that requires authentication for registration.
fix
Ensure that if your Meshblu instance requires authentication for registration, you provide valid
uuid and token in the MeshbluHttp constructor, or that the Meshblu server is configured to allow anonymous registration for the /devices endpoint. For subsequent authenticated calls, always pass the device's uuid and token. error TypeError: MeshbluHttp is not a constructor ↓
cause This error typically occurs when trying to use `MeshbluHttp` as a class with the `new` keyword after incorrectly importing it, especially when mixing CommonJS `require` with expectations of an ESM default export.
fix
Ensure you are using the correct CommonJS import statement:
const MeshbluHttp = require('meshblu-http');. Do not use import MeshbluHttp from 'meshblu-http'; or similar ESM syntax. error Error: connect ECONNREFUSED <hostname>:<port> ↓
cause The Meshblu server specified in the `hostname` and `port` options is not running, is inaccessible from the client's network, or the provided hostname/port are incorrect.
fix
Verify that the Meshblu server is running and listening on the specified hostname and port. Check network connectivity, firewall rules, and ensure the
hostname and port values in the MeshbluHttp constructor are correct for your Meshblu instance. Warnings
breaking The `v10.0.0` major version bump implies breaking changes, though specific API-level changes are not explicitly detailed in the provided release notes, beyond internal build process alterations ('pre-compile coffee before publish'). Users upgrading from `v9.x` should review the GitHub repository for detailed migration guides or changelogs to identify API incompatibilities. ↓
fix Consult the official GitHub repository's release notes or commit history for `v10.0.0` and higher to understand specific API changes and adapt your code accordingly. Test thoroughly after upgrading.
gotcha This library is primarily written with CommonJS (`require()`) exports. While modern Node.js development favors ECMAScript Modules (`import`), `meshblu-http` does not officially support ESM, and attempting to use `import` syntax will likely lead to runtime errors or incorrect module resolution. ↓
fix Always use `const MeshbluHttp = require('meshblu-http');` for importing the library. If you are developing an ESM project, you may need to use a CommonJS wrapper or a build tool that handles CJS interoperability.
gotcha The underlying Meshblu 1.0 platform, which `meshblu-http` is designed to interact with, is explicitly marked as 'preserved for historical reference' on its main GitHub repository, with new development focusing on 'meshblu-core' microservices. This suggests that the HTTP API wrapped by this client might not receive active development or new features, potentially limiting its long-term viability or feature set for new Meshblu deployments. ↓
fix For new projects, consider whether `meshblu-http` aligns with the current Meshblu architecture or if direct interaction with `meshblu-core` components or other protocol clients would be more appropriate. Verify the active status and support for the specific Meshblu HTTP API endpoint you are targeting.
Install
npm install meshblu-http yarn add meshblu-http pnpm add meshblu-http Imports
- MeshbluHttp wrong
import MeshbluHttp from 'meshblu-http';correctconst MeshbluHttp = require('meshblu-http'); - MeshbluHttp Options
const meshbluHttp = new MeshbluHttp({ uuid: 'your-uuid', token: 'your-token' });
Quickstart
const MeshbluHttp = require('meshblu-http');
// Configure Meshblu connection details from environment variables for security
// It's common to have a dedicated Meshblu service running, or use a cloud instance.
const MESHBLU_HOSTNAME = process.env.MESHBLU_HOSTNAME ?? 'localhost';
const MESHBLU_PORT = parseInt(process.env.MESHBLU_PORT ?? '3000', 10);
const MESHBLU_PROTOCOL = process.env.MESHBLU_PROTOCOL ?? 'http';
const meshbluHttp = new MeshbluHttp({
hostname: MESHBLU_HOSTNAME,
port: MESHBLU_PORT,
protocol: MESHBLU_PROTOCOL
});
// Register a new device with Meshblu
console.log(`Attempting to register a new device with Meshblu at ${MESHBLU_PROTOCOL}://${MESHBLU_HOSTNAME}:${MESHBLU_PORT}...`);
meshbluHttp.register({}, function(error, device) {
if (error) {
console.error('Failed to register device:', error.message);
// Handle specific error codes or retry logic
return;
}
console.log('Device registered successfully!');
console.log('UUID:', device.uuid);
console.log('Token:', device.token);
// Example: Authenticate the newly registered device
const authenticatedMeshblu = new MeshbluHttp({
uuid: device.uuid,
token: device.token,
hostname: MESHBLU_HOSTNAME,
port: MESHBLU_PORT,
protocol: MESHBLU_PROTOCOL
});
authenticatedMeshblu.authenticate(function(authError, authResponse) {
if (authError) {
console.error('Failed to authenticate device:', authError.message);
return;
}
console.log('Device authenticated successfully:', authResponse.online ? 'Online' : 'Offline');
// Now you can use authenticatedMeshblu to send messages, create subscriptions, etc.
});
});