Wiznet makers

Hardwired TCP/IP Chapter 12: W55MH32 NetBIOS Examples

In this article, we will provide a detailed explanation on how to implement the NetBIOS function on the W55MH32 chip, and through practical examples, we will teach you how to conduct a PING test using names.

Other network protocols used in this routine, such as DHCP, please refer to the relevant sections. Regarding the initialization process of W55MH32, please refer to the Network Install section. We will not elaborate on this here.

1 Introduction to NetBIOS

NetBIOS (Network Basic Input/Output System, the network basic input/output system) is mainly used for resource sharing among dozens of computers in a small local area network. NetBIOS is an application programming interface (API) that is applied in local area network programs, providing a unified command set for programs to request low-level services. Its function is to provide network services and other special functions for the local area network. Since its inception, NetBIOS has become the foundation of many other network applications. Many local area networks operate based on NetBIOS. In a NetBIOS local area network environment, computers are identified by the system by their names. Each computer in the network has a permanent name compiled in different ways. NetBIOS names are used to identify resources on the network. Programs can start and end sessions using these names. Each program has a unique NetBIOS name. Each network device that supports the application also has a user-defined or internally obtained NetBIOS station name. NetBIOS names can contain up to 16 digits. In the entire resource routing network, character combinations are unique. Before a network device using NetBIOS can fully function on the network, it must first register its NetBIOS name.

2 NetBIOS Features

• Unique naming rule: NetBIOS assigns a unique name of 16 characters to each node in the network. This name serves as the identifier for the node in the network, facilitating user and application identification and access to specific resources.
• Dynamic registration and resolution: When a node connects to the network, it dynamically registers its NetBIOS name in the network. When a node needs to communicate with another node, it uses the name resolution mechanism to convert the NetBIOS name into the corresponding Ethernet address (MAC address). This dynamic registration and resolution process makes network configuration more flexible, allowing nodes to join or leave the network at any time without the need for complex manual configuration.
• TCP-based connection-oriented (TCP) and UDP-based connectionless (UDP) communication are both supported: It supports broadcasting and multicast, and supports three separate services: name, session, and datagram.
• Good compatibility: This protocol has good compatibility and can coexist with other network protocols (such as TCP/IP). In modern network environments, although the TCP/IP protocol dominates, NetBIOS can still play a role in certain specific application scenarios and can interact with applications based on TCP/IP.

3 NetBIOS application scenarios

The W55MH32 can be used with NetBIOS for the following applications:

• Device name resolution: In embedded systems, many devices (such as IoT devices, smart home devices, etc.) may not have a complex DNS system configured. Through the NetBIOS name service, devices can use simple names instead of complex IP addresses for communication.
• Network browsing service: Through NetBIOS broadcasts or point-to-point queries, embedded devices can display their own information in the network resource manager, enabling users to quickly access the devices.

4 The basic workflow of NetBIOS

NetBIOS mainly provides the following three services:

NetBIOS Name Service (Name Service): Responsible for NetBIOS name registration and resolution (corresponding to NBNS).

NetBIOS Datagram Service (Datagram Service): Supports connectionless communication (UDP).

NetBIOS Session Service (Session Service): Supports connection-oriented communication (TCP).

NBNS is a part of NetBIOS and is specifically responsible for implementing the functions of the NetBIOS Name Service. Its role is to convert NetBIOS names into corresponding IP addresses.

The basic workflow of a PC pinging a NetBIOS name is as follows:

Step 1: When the PC pings a NetBIOS name, it first checks if there is a record in its own NetBIOS remote cache name table. If there is, it replaces the NetBIOS name with the IP address; if not, the PC sends a NetBIOS broadcast request.

Step 2: When the device receives the NetBIOS request, it checks if the name in the request matches its own name. If it does, the device replies with its own IP address to the requesting end.

Step 3: After the PC receives the response from the device, it establishes a mapping relationship between the IP address and the NetBIOS name in the NetBIOS remote cache name table and stores it.

Step 4: Based on the mapping relationship in the NetBIOS remote cache name table, the PC replaces the NetBIOS name with the IP for the ping operation.

5 NetBIOS Message Parsing

NetBIOS (Network Basic Input/Output System) messages are used for device discovery and name resolution among computers within a local area network. It operates at the session layer and provides name services via UDP port 137, which is used for mapping host names to IP addresses; UDP port 138 is used for datagram services, supporting unconnected message transmission; and TCP port 139 is used for session services, supporting connected communication.

The format of NetBIOS messages is as follows:

Field Explanation

1. Transaction ID (Transaction ID):

A unique transaction ID used to identify the request and response, facilitating the matching of query and response messages.

2. Flags (Flags):

Indicates the type of message (request/response).

Includes broadcast flags, operation codes, and other control information.

3. Questions (Number of Questions):

Represents the number of names in the current query, usually 1.

4. Answer RRs (Number of Answered Records):

Represents the number of resource records returned in the response.

5. Authority RRs (Number of Authoritative Records):

Represents the number of records of the authoritative name server provided.

6. Additional RRs (Number of Additional Records):

Provides additional supplementary information, such as IP addresses or other supplementary data.

7. Question Name (Query Name):

The NetBIOS name of the query, encoded specially, occupying 16 bytes, ending with 0x00.

8. Question Type (Query Type):

Specifies the type of the query, such as 0x20 indicates a NetBIOS name query.

9. Question Class (Query Class):

Specifies the class of the query, 0x01 indicates IN (Internet query).

Message Example

|Message parsing|
NetBIOS Name Service
   Transaction ID: 0xa753                        (The unique identifier for this query, used to match the request with the response.)
   Flags: 0x0110, Opcode: Name query, Recursion desired, Broadcast                   (This indicates that this is a broadcast query request.)
   Questions: 1                    (Field description: Only query one device name)
   Answer RRs: 0               (In the response message, this field will display the number of records that have been parsed.)
   Authority RRs: 0            (In the response message, it is used to indicate which servers can authorize to respond to this query)
   Additional RRs: 0          (In some NetBIOS responses, it may be used to carry more parsing information.)

|Original message|
a7 54 01 10 00 01 00 00 00 00 00 00

6 The implementation process

Next, let's see how to implement the NetBIOS function on the W55MH32.

Note: The test instance requires that the PC and the W55MH32 be in the same network segment.

In the main loop, call the do_netbios() function as follows:

1. while (1)
2.     {
3.         do_netbios(SOCKET_ID);
4.     }

The do_netbios() function requires an input parameter, which is the socket number. The do_netbios() function is as follows:

 1. void do_netbios(uint8_t sn)
 2. {
 3.     unsigned char state;
 4.     unsigned int  len;
 5.     state = getSn_SR(sn);
 6.     switch (state)
 7.     {
 8.     case SOCK_UDP:
 9.         if ((len = getSn_RX_RSR(sn)) > 0)
10.         {
11.             unsigned char     rem_ip_addr[4];
12.             uint16_t         rem_udp_port;
13.             char             netbios_name[NETBIOS_NAME_LEN + 1];
14.             NETBIOS_HDR      *netbios_hdr;
15.             NETBIOS_NAME_HDR *netbios_name_hdr;
16.             len = recvfrom(sn, (unsigned char *)&netbios_rx_buf, len, rem_ip_addr, &rem_udp_port);
17.             printf("rem_ip_addr=%d.%d.%d.%d:%d\r\n", rem_ip_addr[0], rem_ip_addr[1], rem_ip_addr[2], rem_ip_addr[3], rem_udp_port);
18.             netbios_hdr      = (NETBIOS_HDR *)netbios_rx_buf;
19.             netbios_name_hdr = (NETBIOS_NAME_HDR *)(netbios_hdr + 1);
20.             // If the packet is a NetBIOS query packet
21.             if (((netbios_hdr->flags & ntohs(NETB_HFLAG_OPCODE)) == ntohs(NETB_HFLAG_OPCODE_NAME_QUERY)) && ((netbios_hdr->flags & ntohs(NETB_HFLAG_RESPONSE)) == 0) && (netbios_hdr->questions == ntohs(1)))
22.             {
23.                 printf("netbios name query question\r\n");
24.                 // Decode the NetBIOS package
25.                 netbios_name_decoding((char *)(netbios_name_hdr->encname), netbios_name, sizeof(netbios_name));
26.                 printf("name is %s\r\n", netbios_name);
27.                 // If the query is made against the native Netbios
28.                 if (strcmp(netbios_name, NETBIOS_W5500_NAME) == 0)
29.                 {
30.                     uint8_t       ip_addr[4];
31.                     NETBIOS_RESP *resp = (NETBIOS_RESP *)netbios_tx_buf;
32.                     // Handle the header of the NetBIOS response packet
33.                     resp->resp_hdr.trans_id      = netbios_hdr->trans_id;
34.                     resp->resp_hdr.flags         = htons(NETB_HFLAG_RESPONSE | NETB_HFLAG_OPCODE_NAME_QUERY | NETB_HFLAG_AUTHORATIVE | NETB_HFLAG_RECURS_DESIRED);
35.                     resp->resp_hdr.questions     = 0;
36.                     resp->resp_hdr.answerRRs     = htons(1);
37.                     resp->resp_hdr.authorityRRs  = 0;
38.                     resp->resp_hdr.additionalRRs = 0;
39.                     // Process the header data of the NetBIOS response packet
40.                     memcpy(resp->resp_name.encname, netbios_name_hdr->encname, sizeof(netbios_name_hdr->encname));
41.                     resp->resp_name.nametype = netbios_name_hdr->nametype;
42.                     resp->resp_name.type     = netbios_name_hdr->type;
43.                     resp->resp_name.cls      = netbios_name_hdr->cls;
44.                     resp->resp_name.ttl      = htonl(NETBIOS_NAME_TTL);
45.                     resp->resp_name.datalen  = htons(sizeof(resp->resp_name.flags) + sizeof(resp->resp_name.addr));
46.                     resp->resp_name.flags    = htons(NETB_NFLAG_NODETYPE_BNODE);
47.                     getSIPR(ip_addr);
48.                     memcpy(resp->resp_name.addr, ip_addr, 4);
49.                     // Send a response packet
50.                     sendto(sn, (unsigned char *)resp, sizeof(NETBIOS_RESP), rem_ip_addr, rem_udp_port);
51.                     printf("send response\r\n");
52.                 }
53.             }
54.         }
55.         break;
56.  
57.     case SOCK_CLOSED:
58.         close(sn);
59.         socket(sn, Sn_MR_UDP, NETBIOS_PORT, 0);
60.         break;
61.  
62.     default:
63.         break;
64.     }
65. }

Entering the do_netbios() function will execute a UDP protocol state machine. After receiving the message, it will first determine whether it is a NetBIOS message. If it is a NetBIOS message, it will enter the netbios_name_decoding() function to decode the NetBIOS name. When the name matches the NetBIOS name of W55MH32, it will return the response message.

The netbios_name_decoding() function is as follows:

 1. static int netbios_name_decoding(char *name_enc, char *name_dec, int name_dec_len)
 2. {
 3.     char *pname;
 4.     char  cname;
 5.     char  cnbname;
 6.     int   index = 0;
 7.     // Decode the name of the former NetBIOS
 8.     pname = name_enc;
 9.     for (;;)
10.     {
11.         /* Every two characters of the first level-encoded name
12.      * turn into one character in the decoded name. */
13.         cname = *pname;
14.         if (cname == '\0')
15.             break; // no more characters
16.         if (cname == '.')
17.             break; // scope ID follows
18.         if (cname < 'A' || cname > 'Z')
19.         {
20.             // Not legal.
21.             return -1;
22.         }
23.         cname  -= 'A';
24.         cnbname = cname << 4;
25.         pname++;
26.  
27.         cname = *pname;
28.         if (cname == '\0' || cname == '.')
29.         {
30.             /* No more characters in the name - but we're in
31.        * the middle of a pair.  Not legal. */
32.             return -1;
33.         }
34.         if (cname < 'A' || cname > 'Z')
35.         {
36.             // Not legal.
37.             return -1;
38.         }
39.         cname  -= 'A';
40.         cnbname |= cname;
41.         pname++;
42.  
43.         // Do we have room to store the character?
44.         if (index < NETBIOS_NAME_LEN)
45.         {
46.             // Yes - store the character.
47.             name_dec[index++] = (cnbname != ' ' ? cnbname : '\0');
48.         }
49.     }
50.     return 0;
51. }

7 Run results

After the burning routine was executed, the PHY link was first detected, then the network address was obtained through DHCP and the network address information was printed. Finally, the program began to continuously receive and respond to NetBIOS requests. As shown in the figure below:

8 Summary

This article explains how to implement the NetBIOS function on the W55MH32 chip. Through practical examples, it demonstrates the specific process of conducting name PING tests using NetBIOS, including key steps such as calling the NetBIOS function, request processing, name resolution, and response sending. The article details the concept, characteristics, application scenarios, basic workflow, and message parsing of NetBIOS, helping readers understand its significant role in resource sharing and device communication in small local area networks.

The next article will focus on UPnP, explaining its core principles and applications in network device interconnection, as well as how to implement UPnP functionality on related devices. Stay tuned!

WIZnet is a non-fabrication semiconductor company founded in 1998. Its products include the Internet processor iMCU™, which adopts TOE (TCP/IP Offloading Engine) technology and is based on a unique patented fully hardwired TCP/IP. iMCU™ is designed for embedded Internet devices in various applications.

WIZnet has over 70 distributors worldwide, with offices in Hong Kong, South Korea, and the United States, providing technical support and product marketing.

The region managed by the Hong Kong office includes: Australia, India, Turkey, and Asia (excluding South Korea and Japan).