SNMP Agent routines enable network management features. More...

Structures
struct	SNMP_MIB
	SNMP-MIB Entry info. More...

Functions
netStatus	snmp_trap (const uint8_t ip_addr, uint8_t generic, uint8_t specific, const uint16_t obj_list)
	Send a trap message to the Trap Manager.

netStatus	snmp_set_community (const char *community)
	Change SNMP community to a new community.

Description

SNMP Agent routines enable network management features.

Simple Network Management Protocol (SNMP) is mainly used in network management systems to monitor network-attached devices for conditions that warrant administrative attention. It is the most popular network management protocol in the TCP/IP protocol suite.

Note: The page SNMP Agent gives you more information on the actual usage of the functions and how to work with them in a project.

Code Examples

SNMP Agent MIB Data Template

The following source code is part of the SNMP_Agent_MIB.c template file. This code template enables the developer to define an application specific MIB data table for the SNMP agent:

#include "rl_net.h"
 
// System
extern uint32_t snmp_SysUpTime;
 
// MIB read only integer constants
static const uint8_t sysServices = 79;
 
/* Example
// snmp_agent.c
extern bool LCDupdate;
extern char lcd_text[2][16+1];
extern uint8_t get_button (void);
extern void    LED_Out (uint8_t leds);
 
// Local variables
static uint8_t  LedOut;
static uint8_t  KeyIn;
 
// MIB event callback functions
static void write_leds (int mode) {
  if (mode == MIB_WRITE) {
    LED_Out (LedOut);
  }
}
 
static void read_key (int mode) {
  if (mode == MIB_READ) {
    KeyIn = get_button();
  }
}
*/
 
// MIB data table
const SNMP_MIB snmp_mib[] = {
// ---------- System MIB ----------- 
  // SysDescr Entry
  { MIB_OCTET_STR | MIB_ATR_RO,
    8, {MIB_OID0(1,3), 6, 1, 2, 1, 1, 1, 0},
    MIB_STR("Embedded System SNMP V1.0"),
    NULL },
  // SysObjectID Entry
  { MIB_OBJECT_ID | MIB_ATR_RO,
    8, {MIB_OID0(1,3), 6, 1, 2, 1, 1, 2, 0},
    MIB_STR("\x2b\x06\x01\x02\x01\x01\x02\x00"),
    NULL },
  // SysUpTime Entry
  { MIB_TIME_TICKS | MIB_ATR_RO,
    8, {MIB_OID0(1,3), 6, 1, 2, 1, 1, 3, 0},
    4, &snmp_SysUpTime,
    NULL },
  // SysContact Entry
  { MIB_OCTET_STR | MIB_ATR_RO,
    8, {MIB_OID0(1,3), 6, 1, 2, 1, 1, 4, 0},
    MIB_STR("test@keil.com"),
    NULL },
  // SysName Entry
  { MIB_OCTET_STR | MIB_ATR_RO,
    8, {MIB_OID0(1,3), 6, 1, 2, 1, 1, 5, 0},
    MIB_STR("Evaluation board"),
    NULL },
  // SysLocation Entry
  { MIB_OCTET_STR | MIB_ATR_RO,
    8, {MIB_OID0(1,3), 6, 1, 2, 1, 1, 6, 0},
    MIB_STR("Local"),
    NULL },
  // SysServices Entry
  { MIB_INTEGER | MIB_ATR_RO,
    8, {MIB_OID0(1,3), 6, 1, 2, 1, 1, 7, 0},
    MIB_INT(sysServices),
    NULL },
// ---------- Experimental MIB -----------
  /* Example
  // AddLedOut Entry
  { MIB_INTEGER,
    6, {MIB_OID0(1,3), 6, 1, 3, 1, 0},
    MIB_INT(LedOut),
    write_leds },
  // KeyIn Entry
  { MIB_INTEGER | MIB_ATR_RO,
    6, {MIB_OID0(1,3), 6, 1, 3, 2, 0},
    MIB_INT(KeyIn),
    read_key },
     ...
  */
};
 
const int snmp_mib_size = SNMP_MIB_SIZE(snmp_mib);

Data Structure Documentation

struct SNMP_MIB

SNMP-MIB Entry info.

Data Fields
uint8_t	Type
	Object Type.

uint8_t	OidLen
	Object ID length.

uint8_t	Oid [MIB_OID_SIZE]
	Object ID value.

uint8_t	ValSz
	Size of a variable.

void *	Val
	Pointer to a variable.

void(*	cb_func )(int mode)
	Write/Read event callback function.

Field Documentation

void(* cb_func)(int mode)

Write/Read event callback function.

uint8_t Oid[MIB_OID_SIZE]

Object ID value.

uint8_t OidLen

Object ID length.

uint8_t Type

Object Type.

void* Val

Pointer to a variable.

uint8_t ValSz

Size of a variable.

Function Documentation

netStatus snmp_set_community ( const char * community )

Change SNMP community to a new community.

Parameters

[in] community new community, a null-terminated string.

Returns: status code that indicates the execution status of the function as defined with netStatus.

The function snmp_set_community changes the SNMP community to a new community identified by community.

The argument community is a pointer to a 0-terminated string. The maximum length of the community string is limited to 18 characters.

Code Example

void send_alarm (void) {
  // Send a trap message when alarm input is activated.
  uint16_t obj[2];
 
  // Change the community to "private". 
  snmp_set_community ("private");
 
  // Add "KeyIn" value to trap message. 
  obj[0] = 1;
  obj[1] = 8;    // Index of "KeyIn" entry in MIB table.
  snmp_trap (NULL, 6, 1, obj);
 
  // Restore the community to "public". 
  snmp_set_community ("public");
}

netStatus snmp_trap	(	const uint8_t *	ip_addr,
		uint8_t	generic,
		uint8_t	specific,
		const uint16_t *	obj_list
	)

Send a trap message to the Trap Manager.

Parameters

[in]	ip_addr	IP address of the Trap server or NULL to use Trap server IP address from system configuration.
[in]	generic	generic trap type: 0 = ColdStart trap 1 = WarmStart trap 2 = LinkDown trap 3 = LinkUp trap 4 = AuthenticationFailure trap 5 = EgpNeighborLoss trap 6 = EnterpriseSpecific trap
[in]	specific	specific trap type for generic enterpriseSpecific trap: must be set to 0 for generic traps 0 ... 5
[in]	obj_list	object list included in trap message.

Returns: status code that indicates the execution status of the function as defined with netStatus.

The function snmp_trap sends a message to the Trap Manager.

The argument ip_addr points to the IP address of the Trap server. If the IP address of the Trap Manager is NULL, then the IP address of Trap Server configured in Net_Config_SNMP_Agent.h is used.

The argument generic specifies the generic trap type:

Type	Description
0	coldStart trap
1	warmStart trap
2	linkDown trap
3	linkUp trap
4	authenticationFailure trap
5	egpNeighborLoss trap
6	enterpriseSpecific trap

The argument specific specifies the specific trap type. It must be set to 0 for all generic traps from 0..5. It defines a specific trap type for generic enterpriseSpecific trap.

The argument obj_list points to the objects from the MIB table, which will be included in the trap message variable-bindings. This argument is a pointer to the object list array. This array is of variable size. The first element specifies the count of objects in the object list array, followed by the object MIB index values.

Array Index	Array Value
obj[0]	number of objects n
obj[1]	MIB index of first object
obj[2]	MIB index of second object
..	..
obj[n]	MIB index of last object

If obj_list is NULL, or obj[0] = 0, then no object values will be bound to the trap message.

Note: The maximum number of objects that can be bound to the trap message is limited to 20 objects.