SNMP (Simple Network Management Protocol) is an Internet Standard protocol for collecting and organizing information about managed devices on IP networks and for modifying that information to change device behavior. It is widely used for network monitoring, infrastructure management, and IoT device supervision.
The Weble universal gateway SNMP driver operates as a manager (client) that polls SNMP agents (devices) to read their OID values. It supports all three major versions of the protocol:
The driver also supports SNMP trap receiving, allowing the gateway to listen for unsolicited notifications sent by SNMP agents (e.g. link down, cold start, authentication failure).
Create a new gateway and select the SNMP driver. Configure the target device host and the SNMP version to use. Once the gateway is started, you can either manually insert addresses (OIDs) or use the built-in Walk function to automatically discover all available OIDs on the target device.
Insert a new gateway with the SNMP driver. The minimum required parameters are:
v1, v2c, or v3 depending on the device capabilities.public).Once the gateway is started, right-click on the gateway to open the context menu and select SNMP Methods > Walk. Enter the root OID to scan (e.g. 1 for the full tree, or 1.3.6.1.2.1 for the standard MIB-II subtree). The driver will perform an SNMP walk and automatically import all discovered OIDs as addresses.
The walk progress is displayed as a percentage. Depending on the size of the device MIB tree, this operation can take from a few seconds to several minutes.
MIB (Management Information Base) files provide human-readable names and descriptions for OIDs. When MIB files are uploaded, the driver uses them to resolve OID numbers into meaningful names in the address tree.
To manage MIB files, right-click on the gateway and select SNMP Methods > MIB Files. From this dialog you can:
.mib file from your computer.After uploading MIB files, the address tree is automatically recomputed to display the resolved OID names.
| Label | JSON Key | Description |
|---|---|---|
| Name | name | A descriptive name for this SNMP gateway instance. |
| Cluster ID | cluster | Cluster identifier (integer). Use 0 for single-gateway setups. |
| Description | description | Optional description for this gateway. |
| Role | role | The SNMP role. Currently only manager (SNMP client/manager) is supported. |
| Host | host | IP address or hostname of the target SNMP agent (device). |
| Port | port | UDP port of the SNMP agent. Default: 161. |
| Retries | retries | Number of retry attempts when an SNMP request times out. |
| Timeout | timeout | Request timeout in milliseconds before the driver considers the request as failed. Default: 5000. |
| Version | version | SNMP protocol version: v1, v2c, or v3. This selection controls which authentication parameters are visible (see below). |
| ID bits size | idBitsSize | SNMP request ID bit size: 32 (default) or 16. Use 16 for older devices that do not support 32-bit request IDs. |
The authentication parameters depend on the selected SNMP version.
| Label | JSON Key | Description |
|---|---|---|
| Community String | communityString | The community string used for authentication. This acts as a shared password between the manager and the agent. Default: public. Common values are public (read-only) and private (read-write). |
| Label | JSON Key | Description |
|---|---|---|
| Context | context | SNMP v3 context name. Leave empty unless the target device requires a specific context. |
| User Name | user.name | The SNMPv3 username configured on the target device. |
| Security Level | user.level | Security level: noAuthNoPriv (no authentication, no encryption), authNoPriv (authentication only), or authPriv (authentication and encryption). |
| Auth Protocol | user.authProtocol | Authentication protocol: md5 or sha. Only visible when the security level includes authentication. |
| Auth Key | user.authKey | Authentication passphrase/key. Only visible when the security level includes authentication. |
| Priv. Protocol | user.privProtocol | Privacy (encryption) protocol: des or aes. Only visible when the security level is authPriv. |
| Priv. Key | user.privKey | Privacy passphrase/key. Only visible when the security level is authPriv. |
The SNMP driver can also act as a trap receiver, listening for unsolicited notifications from SNMP agents on the network.
| Label | JSON Key | Description |
|---|---|---|
| Receiver | receiver | Enable or disable the SNMP trap receiver. |
| Receiver port | receiverPort | UDP port on which to listen for incoming traps. Default: 162. Only visible when receiver is enabled. |
| Receiver auth | receiverAuth | If enabled, rejects unauthenticated trap messages. Only visible when receiver is enabled. |
When the receiver is enabled, incoming traps are emitted on special addresses:
%snmp_trap:receiver — receives all raw trap notifications (full PDU payload).%snmp_trap:all — receives all trap events with their type.%snmp_trap:<type> — receives traps filtered by type: LinkDown, LinkUp, ColdStart, AuthenticationFailure, EgpNeighborLoss, EnterpriseSpecific.{
"role": "manager",
"host": "192.168.1.100",
"port": 161,
"retries": 1,
"timeout": 5000,
"receiver": false,
"receiverPort": 162,
"receiverAuth": false,
"version": "v2c",
"idBitsSize": 32,
"communityString": "public"
}
SNMP v3 example:
{
"role": "manager",
"host": "192.168.1.100",
"port": 161,
"retries": 1,
"timeout": 5000,
"receiver": false,
"version": "v3",
"idBitsSize": 32,
"context": "",
"user": {
"name": "myuser",
"level": "authPriv",
"authProtocol": "sha",
"authKey": "my_auth_passphrase",
"privProtocol": "aes",
"privKey": "my_priv_passphrase"
}
}
SNMP addresses use the prefix %snmp: followed by the OID name or number:
%snmp:sysDescr — named OID (resolved from MIB files)%snmp:1.3.6.1.2.1.1.1 — numeric OIDWhen OIDs are discovered via the Walk function with MIB files loaded, the addresses are automatically named using the MIB-resolved names and organized in a tree structure based on the OID hierarchy.
| Label | JSON Key | Description |
|---|---|---|
| OID | oid | The SNMP Object Identifier to read from the agent. Can be entered as a numeric dotted notation (e.g. 1.3.6.1.2.1.1.1) or as a name if MIB files are loaded. |
| Polling | polling | Polling interval in milliseconds. If set, the driver will periodically read this OID at the specified interval. The minimum effective polling interval is 1000 ms. If left empty or set to 0, the address is only read once at startup. |
| Description | description | Optional description for this address. |
| Log | log | Logging mode: never (no logging), on update (log only when value changes), always (log every poll), or a duration in milliseconds for timed logging. |
Each SNMP address has the following properties:
| Property | Value |
|---|---|
| Readable | Yes |
| Writable | No (read-only) |
| Routable | Yes |
| Loggable | Yes |
Note: The SNMP driver is currently read-only. Writing values to SNMP agents (SET operations) is not supported.
{
"oid": "1.3.6.1.2.1.1.3.0"
}
When the trap receiver is enabled (see section 2.3), trap-specific addresses are automatically created using the %snmp_trap: prefix. These addresses receive values whenever a matching trap notification arrives.
| Address | Description |
|---|---|
%snmp_trap:receiver |
Raw trap notification payload (full PDU with varbinds and sender info). |
%snmp_trap:all |
All trap events with their type as the first element. |
%snmp_trap:LinkDown |
Link down notifications. |
%snmp_trap:LinkUp |
Link up notifications. |
%snmp_trap:ColdStart |
Device cold start (reboot) notifications. |
%snmp_trap:AuthenticationFailure |
Authentication failure notifications. |
%snmp_trap:EgpNeighborLoss |
EGP neighbor loss notifications. |
%snmp_trap:EnterpriseSpecific |
Vendor-specific enterprise trap notifications. |
These trap addresses are routable like any other address. They can be used in routes to forward trap data to other protocols (e.g. MQTT, BACnet) or to trigger alerts via SMTP or SMS drivers.
| Property | Value |
|---|---|
| Address regex | %snmp:<name> or %snmp_trap:* |
| Readable | Yes (triggers SNMP GET on the OID) |
| Writable | No — always returns "read only" |
| Remanent | Only if adr.json.remanent == true |
// Reads the OID from the SNMP agent and returns the decoded value
readValue('%snmp:sysDescr', function(err, value) {
// value = "Linux gateway 5.4.0 ..."
})
The address must have json.oid set to a valid numeric OID (e.g. 1.3.6.1.2.1.1.1).
Trap addresses receive values automatically when SNMP traps arrive:
%snmp_trap:receiver — raw PDU payload with varbinds and sender info%snmp_trap:all — all trap events with type%snmp_trap:LinkDown, LinkUp, ColdStart, AuthenticationFailure, EgpNeighborLoss, EnterpriseSpecificjson.polling (minimum 1000ms)/^[0-9](\.[0-9]+)*$/scanSubtree has a 15-second timeout