NetBIOS - try it out

[mark]

Hi All

I hope that no one is getting the impression that there is no development work progress at the moment. It is true that new service pack releases are a bit (too) quiet but this is rather to do with the fact that there is a lot of activity requiring rather more work to get everything in line for something official. [On top of this is a generally high level of 'project' work which is diverting more energy that anticipated [positive side is that there will be more features soon such as graphical LCD support...], plus some new chip work which is proving more complicated than expected before it can be shown]. All-in-all well behind on all fronts, but battling and having some fun on the way at least.

So I though it would be nice to give something general which may well prove useful for a number of users. It is not a big thing but can prove useful, especially when you have a device configured to gets its configuration from a DHCP server.

It is all about NetBIOS

First a typical case of its use.
If you have a device configured to get its IP set up from a DHCP server it is not always that easy to indicate its configuration to a user (or find it out yourself).
If you use the simulator, the IP address is displayed after DHCP resolution has been achieved (useful for yourself as developer but not for an end-user).
If you have a display or a serial port it is usually possible to display the present configuration, but this is only useful in some situations.
If you can monitor the network using Ethereal (or similar) you can see the setting obrained, but this is hardly a user friendly approach!!
Even if you are not using DHCP, but have set up a device with fixed setting, often its address is forgotten and so it has to be found by using one of the above methods or even by setting it back to its default state (typically done by pressing an input switch on power up).

Working with a name rather than an IP address

This is where NetBIOS comes in - it allows you to communicate with the device by using its name.
In the demo project the device has a user configurable name (default "uTasker Number 1") and this can easily be set up to be used as its name in the network by using the new NetBIOS support. [in fact the default name is too long for NetBIOS so has to be shortened by one to the maximum of 15 characters - the name is not case sensitive so both capitals and small letters can be freely used. I will assume the name "uTasker-1" in the following discussion].
To access its web server, it can be addressed from the browser by entering the URL http ://uTaster-1, or its FTP server by ftp ://uTasker-1. It can also be pinged by using ping uTasker-1 etc. If several devices are in the network just make sure that each has a unique device name, in the same way that they also need unique IP configurations.

With a device supporting NetBIOS it is therefore possible to work with it in a local network without ever needing to actually know its IP address.

How to set it up in your project

First of all you will need a new file called NetBIOS.c which you can add to your project (simulator and/or target). This file is available in its initial form at the following address: http://www.uTasker.com/software/test/NetBIOS.c

This version works without any other header files but the project needs to be configured as follows to add the option:
In config.h add the following to the UDP protocol group (and ensure that UDP itself is enabled!):

Code: [Select]

            #define USE_NETBIOS                                          // enable NetBIOS - needs UDP
Then add the following just below it:

Code: [Select]

            #ifdef USE_NETBIOS
                #define NETBIOS_SOCKET 1
                #define SUPPORT_SUBNET_BROADCAST                         // NetBIOS needs to receive sub-net broadcast frames
            #else
                #define NETBIOS_SOCKET 0
            #endif
and finally
            #define UDP_SOCKETS   (DHCP_SOCKET + DNS_SOCKET + TFTP_SOCKET + NETBIOS_SOCKET + USER_UDP_SOCKETS) // the number of UDP sockets supported
to ensure that there are adequate UDP ports in the UDP pool for the new NetBIOS server.

In a user file (such as in the initialision part of application.c) start the NetBIOS server:

Code: [Select]

  #ifdef USE_NETBIOS
        fnStartNetBIOS_Server(parameters->cDeviceIDName);               
  #endif
To ensure the project compiles without warning or even errors, add the prototype for the new function to tcpip.h:
    extern int fnStartNetBIOS_Server(CHAR *name);               


Here the device ID (a null-terminated string) is set to be used as name. This can of course be changed to any string (limited to 15 characters) if another source for the name is prefered.

That was it - the server simply responds to NetBIOS queries in the background and the rest works as before.

A small warning

The new NetBIOS support is limited to handling single queries in a very lean way. Take a look at the file to see how simple it is to do this (it simply manipulates the query directly in the LAN input buffer and send this back with the local IP details). It may not work in all cases but a single query is the standard method used by a real application - and there may be some other not yet known issues.
Use it and inform me if you do have any problems so that your case can be added to the presently minimal solution.
The code has however been constructed to silently discard NetBIOS frames if they do not conform and so the code should never be able to cause any system problems (commonly known as 'to crash').

Note that NetBIOS works with sub-net broadcasts which is automatically activated by the new code in the configuration. Should your project base not support this option NetBIOS will not be able to work so check latest service packs (I see it is not in the SAM7X pack so contact me for the files if you are interested).

If you have any problems or would like to discuss NetBIOS extensions feel free to discuss here.

Good luck

regards

Mark



Additional notes:
Since NetBIOS communicates using sub-net broadcast frames you need to be careful with the network mask setting when not using DHCP. If for example you set a network mask to be 255.255.254.0 but the local network uses 255.255.255.0 NetBIOS will not work. The reason is that the PCs sub-net broadcast frames (assume 192.168.0.1 as PC IP address) will be  192.168.0.255. This is a broadcast in the 255.255.255.0 subnet but not in the 255.255.254.0 sub-net, which needs 192.168.1.255 - so this will not be received by the device in this case.
Using  DHCP will also ensure that the entire sub-net set-up is correct.

If the IP address of the board is changed the PCs using NetBIOS which have the NAME:IP combination in their cache will not be able to find the board at its new address. In this case the Windows nbtstat -R command can be used to purge the cache, which causes a new request to be sent out on the network and so the entry updated.


 

[seulater]

Now, that this is all included with the new 1.4 release, where is the NetBIOS name defined at ?

[mark]

Hi

In config.h the define USE_NETBIOS is set as standard in the USE_UDP section.

This was added about 2 years ago so is not V1.4 specific.

Regards

Mark

[seulater]

But where does one give NetBios a name for the network ?

[mark]

Hi

fnStartNetBIOS_Server(parameters->cDeviceIDName);

The name is passed as a string when the server is started.
In the demo this is the same string that is used as device ID (this is also displayed when connecting via TELNET or on the start page of the web server). The name can also be changed on the web server page.
The default is defined in application.c in const PARS cParameters = {

    {'u', 'T', 'a', 's', 'k', 'e', 'r', ' ', 'N', 'u', 'm', 'b', 'e', 'r', ' ', '1',0,0,0,0,0},
Note however this is in fact a little too long for NETBIOS and NETBIOS doesn't like spaces either, but this can be simply changed as required.

If this source is not suitable any other string can be used.

Regards

Mark

[seulater]

Thank you.

[mark]

Hi All

On a Windows PC the following two command can be usedful to view the NetBIOS hostname table or to purge and reload the table:

nbtstat –c             [lists the name table]

nbtstat –R             [purges and reloads the name table]

Beware that the options are case-sensitive!

Regards

Mark