Copyright © Marius Milner, 2003-2004
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.
| 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. |
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.
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 |
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).
| 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 |
| 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 |
| 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. |
| 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 |
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.
| 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 |
| 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 |
| 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) |
| 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 |
| 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