How to read and write .NS1 files

Copyright © Marius Milner, 2003-2004

Important Note

This document is provided as-is and with no support or warranty, implied or otherwise. You may not redistribute it, even in unmodified form. You may redistribute source code, compiled libraries or executables based on it. You may store a copy on your own computer for backup or reference purposes. Don't be evil.

History of this document

Date What changed
April 17, 2003 Initial version detailing file versions 8 and below.
May 8, 2003 Added table of program/file version numbers.
December 6, 2003 Details of file version 11,12.
April 22, 2004 Update for software release 0.4.0.

Introduction

This document describes the NetStumbler file format. It is primarily intended for people wanting to read NS1 files (for example, to be able to import them into mapping software), however there may be others that want to write their own NS1 files. If you do write your own NS1 files, it is your responsibility to make sure that you test them with NetStumbler.

You are expected to be able to understand the data fields that you care about, and silently copy the ones that you don't care about.

File versions

As the file format changes, the version number increases. Each version of NetStumbler and MiniStumbler is able to read files created by earlier versions; however they only write the version in effect when they were released. The following table describes the file version numbers and which releases of NetStumbler and MiniStumbler use them. Please note that only file versions highlighted with a yellow background will be seen in practice. I have some files of the other versions, but nobody else does and I don't plan to give them away.

File Version Date Introduced What was added Program Versions that write this File Version
NetStumbler MiniStumbler
1 May 14, 2001 SSID, BSSID, maximum signal, minimum noise, maximum SNR, channel number 0.2 None
2 May 17, 2001 GPS position of AP None None
3 May 22, 2001 For each AP, a record of data containing time, signal, noise, and GPS None None
4 May 25, 2001 AP Name None None
5 June 8, 2001 Time as FILETIME not time_t None None
6 June 12, 2001 Multiple channel numbers as 32-bit field 0.3, 0.3.10, 0.3.20, 0.3.21, 0.3.22, 0.3.23 0.3.23
7 June 23, 2002 Channel numbers None None
8 July 2, 2002 IP Address of AP 0.3.30 None
9 August 21, 2002 Minimum signal, maximum noise None None
10 April 28, 2003 Reported maximum data rate None None
11 June 4, 2003 IP Subnet and Mask Early 0.3.99 Early 0.3.99
12 December 6, 2003 AP Misc Flags 0.3.99, 0.4.0 0.3.99, 0.4.0

Note about data types

Most structures are variable-length. No provision is made to assist file indexing or skipping unwanted data.

No padding bytes are added.

All integer types are little-endian (least significant byte first).

For those not familiar with it, a FILETIME is a 64-bit integer defined to be the number of 100-nanosecond increments since January 1, 1601 (UTC).

Data Format Description - Current

NS1 File (All Versions)

Size (Bytes) Name Type Description
4 dwSignature char[4] File Signature ('NetS')
4 dwFileVer uint32 File Format Version
4 ApCount uint32 Number of APINFO entries that follow
Variable ApInfo APINFO[] ApCount APINFO entries

APINFO Entry (Version 12)

Size (Bytes) Name Type Description
1 SSIDLength uint8 Length of SSID
SSIDLength SSID char[] SSID (SSIDLength characters, no terminating null)
6 BSSID uint8[6] BSSID
4 MaxSignal int32 Maximum reported signal level, dBm
4 MinNoise int32 Minimum reported noise level, dBm
4 MaxSNR int32 Maximum reported signal-to-noise ratio, dB
4 Flags uint32 802.11 capability flags
4 BeaconInterval uint32 Beacon Interval, KÁs
8 FirstSeen FILETIME Time first seen
8 LastSeen FILETIME Time last seen
8 BestLat double Estimated Latitude
8 BestLong double Estimated Longitude
4 DataCount uint32 Number of APDATA entries that follow
Variable ApData APDATA[] DataCount APDATA entries
1 NameLength uint8 Length of Name
NameLength Name char[] Name (NameLength characters, no terminating null)
8 Channels uint64 Bit field indicating channel activity
4 LastChannel uint32 Last reported channel
4 IPAddress uint32 IP Address
4 MinSignal int32 Minimum reported signal level, dBm
4 MaxNoise int32 Maximum reported noise level, dBm
4 DataRate uint32 Highest reported data rate, units of 100 kbps
4 IPSubnet uint32 IP Subnet address
4 IPMask uint32 IP Subnet mask
4 ApFlags uint32 Miscellaneous Flags
4 IELength uint32 Number of bytes that follow (0 except when using NDIS 5.1 with a WPA capable driver)
IELength InformationElements uint8[] 802.11 Information Elements

APDATA Entry (Version 5 and up)

Size (Bytes) Name Type Description
8 Time FILETIME Time that this data was collected
4 Signal int32 Reported Signal, dBm
4 Noise int32 Reported Noise, dBm
4 Location Source int32 Kind of location fix (None=0, GPS=1)
0 or sizeof(GPSDATA) GpsData GPSDATA If LocationSource is None(0), this structure is not present.

GPSDATA Entry (Version 3 and up)

Size (Bytes) Name Type Description
8 Latitude double Reported latitude
8 Longitude double Reported longitude
8 Altitude double Reported altitude
4 NumSats uint32 Number of satellites in view of GPS receiver
8 Speed double Reported speed
8 Track double Reported track
8 MagVariation double Reported magnetic variation
8 Hdop double Reported HDOP

Data Format Description - Old Versions

You may see NS1 files with older version numbers than the current one. The following tables will help you to interpret them. Entries are highlighted with a pink background if they were deleted or replaced in the next file version, and with a green background if they are new since the previous documented version.

APINFO Entry (Version 11)

Size (Bytes) Name Type Description
1 SSIDLength uint8 Length of SSID
SSIDLength SSID char[] SSID (SSIDLength characters, no terminating null)
6 BSSID uint8[6] BSSID
4 MaxSignal int32 Maximum reported signal level, dBm
4 MinNoise int32 Minimum reported noise level, dBm
4 MaxSNR int32 Maximum reported signal-to-noise ratio, dB
4 Flags uint32 802.11 capability flags
4 BeaconInterval uint32 Beacon Interval, KÁs
8 FirstSeen FILETIME Time first seen
8 LastSeen FILETIME Time last seen
8 BestLat double Estimated Latitude
8 BestLong double Estimated Longitude
4 DataCount uint32 Number of APDATA entries that follow
Variable ApData APDATA[] DataCount APDATA entries
1 NameLength uint8 Length of Name
NameLength Name char[] Name (NameLength characters, no terminating null)
8 Channels uint64 Bit field indicating channel activity
4 LastChannel uint32 Last reported channel
4 IPAddress uint32 IP Address
4 MinSignal int32 Minimum reported signal level, dBm
4 MaxNoise int32 Maximum reported noise level, dBm
4 DataRate uint32 Highest reported data rate, units of 100 kbps
4 IPSubnet uint32 IP Subnet address
4 IPMask uint32 IP Subnet mask

APINFO Entry (Version 8)

Size (Bytes) Name Type Description
1 SSIDLength uint8 Length of SSID
SSIDLength SSID char[] SSID (SSIDLength characters, no terminating null)
6 BSSID uint8[6] BSSID
4 MaxSignal int32 Maximum reported signal level, dBm
4 MinNoise int32 Minimum reported noise level, dBm
4 MaxSNR int32 Maximum reported signal-to-noise ratio, dB
4 Flags uint32 802.11 capability flags
4 BeaconInterval uint32 Beacon Interval, KÁs
8 FirstSeen FILETIME Time first seen
8 LastSeen FILETIME Time last seen
8 BestLat double Estimated Latitude
8 BestLong double Estimated Longitude
4 DataCount uint32 Number of APDATA entries that follow
Variable ApData APDATA[] DataCount APDATA entries
1 NameLength uint8 Length of Name
NameLength Name char[] Name (NameLength characters, no terminating null)
8 Channels uint64 Bit field indicating channel activity
4 LastChannel uint32 Last reported channel
4 IPAddress uint32 IP Address

APINFO Entry (Version 6)

Size (Bytes) Name Type Description
1 SSIDLength uint8 Length of SSID
SSIDLength SSID char[] SSID (SSIDLength characters, no terminating null)
6 BSSID uint8[6] BSSID
4 MaxSignal int32 Maximum reported signal level, dBm
4 MinNoise int32 Minimum reported noise level, dBm
4 MaxSNR int32 Maximum reported signal-to-noise ratio, dB
4 Channels32 uint32 Bit field indicating channel activity
4 Flags uint32 802.11 capability flags
4 BeaconInterval uint32 Beacon Interval, KÁs
8 FirstSeen FILETIME Time first seen
8 LastSeen FILETIME Time last seen
8 BestLat double Estimated Latitude
8 BestLong double Estimated Longitude
4 DataCount uint32 Number of APDATA entries that follow
Variable ApData APDATA[] DataCount APDATA entries
1 NameLength uint8 Length of Name
NameLength Name char[] Name (NameLength characters, no terminating null)

APINFO Entry (Version 1)

Size (Bytes) Name Type Description
1 SSIDLength uint8 Length of SSID
SSIDLength SSID char[] SSID (SSIDLength characters, no terminating null)
6 BSSID uint8[6] BSSID
4 MaxSignal int32 Maximum reported signal level, dBm
4 MinNoise int32 Minimum reported noise level, dBm
4 MaxSNR int32 Maximum reported signal-to-noise ratio, dB
4 LastChannel uint32 Last active channel number
4 Flags uint32 802.11 capability flags
4 BeaconInterval uint32 Beacon Interval, KÁs
4 FirstSeen time_t Time first seen
4 LastSeen time_t Time last seen

APDATA Entry (Versions 3-4)

Size (Bytes) Name Type Description
4 Time time_t Time that this data was collected
4 Signal int32 Reported Signal, dBm
4 Noise int32 Reported Noise, dBm
4 Location Source int32 Kind of location fix (None=0, GPS=1)
0 or sizeof(GPSDATA) GpsData GPSDATA If LocationSource is None(0), this structure is not present.

 


Copyright ę Marius Milner, 2003-2004