Using the N: Device - FujiNetWIFI/fujinet-firmware GitHub Wiki

To facilitate network functionality on #FujiNet, an N: Device has been created. It provides an easy way to access a variety of network protocols, including:

• TCP
• UDP
• FTP
• HTTP
• TNFS

For protocols that support file-system operations (such as HTTP, FTP, and TNFS) the N: device provides operations to read and write files stored on file-systems exposed by these protocols.

To use the N: Device, it must be loaded into memory. This is provided by the NDEV.COM handler program on the fnc-tools disk. It is typically loaded into memory at boot, renamed to a file like AUTORUN.SYS, on DOS 2.5 or DOS XL, AUTORUN.AR0 on MyDOS, AUTORUN.AU0 on XDOS or LiteDOS, etc.

You can find DOS disks preconfigured with the N: device handler at TNFS server apps.irata.online/Atari_8-Bit/DOS/.

Once loaded, a banner is shown, and the handler is positioned into memory directly at MEMLO, altering it to protect it during use. The handler also protects itself so that it is re-initialized at reset. The banner is re-shown at reset to indicate that it is still available.

#FUJINET READY

N: Device operation can quickly be verified by using it to load a piece of software. For example, from BASIC:

#FUJINET READY 

READY
RUN "N:HTTP://FUJINET-TESTING.IRATA.ONLINE/BLACKJACK.BAS"

If everything is working as it should be, you should see a game of Blackjack running.

If you instead see:

ERROR-    130

The N: device handler is not loaded! Read the previous section titled "Loading the N: Device" and confirm the #FUJINET READY banner displays on boot.

If you see:

ERROR-    138

Please check to make sure your FujiNet is working correctly elsewhere.

If you see:

ERROR-   21

or another error, please let one of the #FujiNet team know.

At the heart of the N: device, is the N: devicespec. Like devicespecs for other devices, this specifies a path to a particular resource, in this context, on a network. It consists of the following syntax:

N[x]:<PROTO>://<PATH>[:PORT]/

The parts in <> are required, the parts in [] are optional.

In detail:

• x — a unit number. There are 4 network devices, N1: to N4: if a number isn't specified, unit 1 is assumed.
• <PROTO> — a network protocol, currently, the following protocols are supported:
  • TCP
  • UDP
  • HTTP
  • FTP
  • TNFS
• <PATH> — a unique way to identify a network resource, dependent on the protocol chosen. Please read below to see what values are valid for the desired protocol.
• [PORT] — a number from 1-65535 specifying the desired network port for a protocol. This is used when the default network port for a protocol isn't what's desired.

In addition, the N: device has the concept of a "current directory" or "prefix" which can be specified by the user to automatically be pre-pended to the user's input. This can save a significant amount of typing for long protocol addresses.

For example, The prefix for N: could be set to HTTP://ATARI-APPS.IRATA.ONLINE/, and when the user attempts to retrieve N:BURIEDBU.COM, the #FujiNet will automatically resolve the devicespec to: N:HTTP://ATARI-APPS.IRATA.ONLINE/BURIEDBU.COM. The NCD tool, as documented later, can be used to set this value.

The purpose of the N: device is to make it possible for the Atari computer to talk various protocols by using the #FujiNet to provide an I/O channel that the Atari can understand. Since there are many different network protocols in use on the Internet, the goal here is to provide as many of these as possible so that the Atari can easily talk to a wide variety of hosts on the network.

The most basic of these are the TCP and UDP protocols, which provide the lowest level of communication possible on TCP/IP. Other, higher level protocols try to help take care of mundane details involved in working with TCP and UDP to either abstract them for filesystem use, or to make them easier to target program development.

What follows is a short description of each protocol and the devicespecs used for each.

Note: The N: devicespecs resemble URI's used in protocols like HTTP, and in fact that is precisely what they are. It was decided that this was the best way to accomodate the parameters of a wide variety of protocols in a very efficient manner.

This protocol can be used to open up a connection to a TCP socket specified by host and port. This can be used, for example, to initiate TELNET or raw terminal connections, as well as talk to services running on TCP ports on which a protocol abstraction does not exist, yet.

TCP (Transmission Control Protocol) connections are stream oriented, the TCP/IP network does all of the hard work of ensuring that data sent via this method arrives from one host to another not only reliably, but also in the correct order.

Note: Due to resource limitations, there is a maximum of 4 simultaneous TCP connections. An error will be returned if more than this many TCP cconnections are attempted simultaneously.

The format of a TCP devicespec is:

N[x]:TCP://<HOST>[:PORT]/

Where:

• <HOST> is a host name or IPv4 address.
• [:PORT] is the port number to use. If not specified, 23 is used as the port number (corresponding to TELNET).

Examples:

To connect to address 192.168.1.1 on port 1234, use:

N:TCP://192.168.1.1:1234/

If a server (listening) connection is desired, use the following devicespec form:

N:TCP://:<PORT>/

This will open a listening socket that will allow incoming connections. To utilize this, you must issue an ACCEPT command (XIO 41) when a client is waiting to indicate that the client should be attached to the N: device.

Example:

To listen for a TCP connection on port 6502:

N:TCP://:6502/

UDP protocol connections are datagram, or packet oriented, and have none of the conveniences of TCP built in. They do have the advantage that they can be sent efficiently to many different destinations, so long as the program using them takes care of cases where the data does not arrive, or arrives out of order. This makes UDP very advantageous for programs like games that send small bits of information to many participants.

The format of a UDP devicespec is:

N[x]:UDP://<HOST>[:PORT]//

Where:

• <HOST> is a host name or IPv4 address.
• [:PORT] is the port number to use. If not specified, 6502 is used for the port number.

If a server, or listening connection is desired, use the following devicespec form:

N:UDP://:<PORT>/

Since UDP doesn't explicitly establish connections between hosts, the source address of the last received packet is persisted and used for any output.

With this protocol, #Fujinet can utilize most of the common HTTP operations such as GET, POST, PUT, and DELETE. This means that the Atari can, through the N: device, read or even write files stored on a web server.

If HTTPS is specified, then an encrypted TLS (née SSL) connection is negotiated. This allows the Atari to communicate with secure web sites and services.

The format of an HTTP or HTTPS devicespec is:

N[x]:<HTTP|HTTPS>://[username:password@]<PATH>[:PORT]/[?queryvar=queryvalue&...]

HTTP queries are supported, and username and password can be passed in the URL (which will cause some form of HTTP authentication to be performed.)

Example:

To retrieve the file BURIEDBU.COM from HTTP host ATARI-APPS.IRATA.ONLINE, use the following devicespec:

N:HTTP://ATARI-APPS.IRATA.ONLINE/BURIEDBU.COM

Note: HTTPS connections incur a slight pause on open, as the #FujiNet needs to negotiate encryption with the host.

The FTP protocol allows the N: device to read and write to files exposed via the FTP (File Transfer Protocol).

The format of an FTP devicespec is:

N[x]:FTP://[username:password@]<HOSTNAME>[:PORT]/<PATH>

Where:

• x — the unit number, from 1-4
• [username:password] — an optional username and password. Anonymous login is done if one is not specified.
• <HOSTNAME> — the host name or IPv4 address of the FTP server
• [:PORT] — an optional control port number. The default port number of 21 is used if one is not specified.
• <PATH> — the path name to the file on the FTP server.

Notes:

• If a username is not specified, Anonymous login with the password of [email protected] is used.
• If a port is not used, port 21 is assumed.
• EPSV commands are used to establish the data port connection to the server.
• A CWD command is issued to the desired path before any file transfer commands are issued.
• An NLST command is issued in response to asking for a directory.
• Random access (NOTE/POINT) is currently not supported.
• File deletion is supported.
• File renaming is supported.
• Lock and Unlock are not supported.
• Connections are not persisted: a full log-in/log-out cycle is done for each and every file operation, just like a web browser.

The TNFS protocol allows the N: device to access TNFS file servers. It differs from the TNFS support for "D:" devices in that instead of emulating a disk drive, and doing sector-level operations on a specific disk image, the N: device can operate on individual files stored on a TNFS file server.

The format of a TNFS filespec is:

N[x]:TNFS://<HOSTNAME>[:PORT]/<PATH>

Where:

• x — the unit number, 1 to 4
• <HOSTNAME> — the host name or IP address of desired TNFS server.
• [:PORT] is the optional port number. If one is not specified, UDP port 16384 is used.
• <PATH> is the full path to the file stored on the TNFS server.

Notes:

• The TNFS server is mounted, the file operation is done, and the TNFS server is unmounted.
• The TNFS server is always mounted from the root directory. (/)
• Anonymous login is always used - username and password are currently not supported.
• Rename is supported.
• Delete is supported.
• Lock/Unlock is not supported.
• NOTE/POINT WILL be supported.
• If the TNFS server is already mounted by a D: device, the mount and unmount steps will not be performed, allowing both the N: and D: devices to use the same server.

The N: tools - currently NCD, NPWD, NCOPY, NDEL, NREN, and NLOAD - are all provided as part of the fnc-tools.atr disk image present on fujinet.online. These tools allow you to either change the operation of the N: device or to access network resources without needing to load the N: device driver. This is possible because these utilities communicate with the N: device entirely over SIO, and thus do not require NDEV to be loaded.

All of the N: tools, like the rest of fnc-tools, have a corresponding .DOC file containing documentation on how to use each command. What follows is a terse abbreviation of those manual pages.

Some network resources point to files stored on file-systems, and sometimes it may be desirable to easily map the N: device to a specific folder on such a filesystem to cut down on the amount of user input required to locate a particular file on a network filesystem. NCD can be used to change the directory of an N: device.

The N: tools are designed to work under both menu based DOSes such as Atari DOS 2.5/MyDOS, as well as CLI based DOSes like DOS XL/SpartaDOS, and will adapt themselves appropriately - either accepting parameters from the command line or asking for these parameters interactively.

The command format for NCD is as follows:

NCD [N[x]:][PROTO:]//[HOST][:PORT]/[PATH]

Notice that ALL of these parameters are optional. If no arguments are specified, then the directory prefix is cleared.

• x — the unit number from 1-4. If a unit number, or the N: is not specified, N1: is assumed.
• [PROTO:] — the desired protocol
• [HOST] — the host name
• [:PORT] — the port number 1-65535
• [PATH] — the desired path to the resource

If only the PATH is specified, the path is assumed to be relative to the currently stored directory prefix, and the new user supplied path is added to the end. This allows you to quickly traverse directory trees while looking at disk directories.

Example:

NCD N:games/

If the parameter passed to NCD is "/", then the entire path is removed, keeping the protocol, host name, and port. This is akin to re-starting at the root directory of a filesystem.

For example, this changes N: to /

NCD /

If the parameter passed to NCD is "..", then the last directory element in the directory prefix is removed. This can be used to return to a parent directory.

Example:

NCD ..

You must end a directory name in / to let FujiNet know that this is a directory and not a file.

This is a directory:

N:FTP://FTP.PIGWA.NET/stuff/collections/

This is a file:

N:FTP://FTP.PIGWA.NET/welcome.msg

This allows you to map an N: device DIRECTLY to a file, and thus be able to use the N: device in programs that assume that devicespecs other than D: can't specify files. For example, you could enter the command:

NCD N:FTP://FTP.PIGWA.NET/stuff/collections/holmes cd/Holmes 2/Atari Archives/Antic Files/88/FROG.EXE

and N: would directly point to FROG.EXE. You can now use DOS XL's COPY command to copy the file:

COPY N: D1:FROG.COM

Should you accidentally specify a directory as a file, you can back out by simply specifying ".." as shown above.

NPWD is the complement to NCD, showing the value of the current working directory. It only has one parameter, the specific N: device to query. If one isn't specified, "N1:" is assumed.

D1:NPWD N:
FTP://FTP.PIGWA.NET/stuff/collections/holmes cd/Holmes 2/Atari Archives/Antic Files/88/

If no directory prefix is set, then the following message is returned:

NO PREFIX SET

NDIR can be used to retrieve a directory from a network file system. It only has one parameter, the desired N: devicespec.

NDIR <devicespec>

As with NCD, if N: is not specified, "N1:" is assumed. If a filename spec isn't specified, the wildcard "*" is assumed. If parameters aren't specified, interactive mode is assumed, and you are prompted for the path.

D1:NDIR N:FTP://FTP.PIGWA.NET/
Changelog.html
lost+found
stuff
upload
upload2
welcome.msg

D1:

This utility can be used to copy files between network file systems in one of three ways:

• From a CIO device, such as D:, to an N: device
• From an N: device to a CIO device, such as D:
• From one N: device to another

If command line parameters aren't specified, or you are using a menu-based DOS, the following prompt is displayed:

NET COPY--FROM, TO?

Allowing you to enter the copy parameters.

The FROM and TO devicespecs must be separated by a comma. You may optionally place a space after the comma.

Note: The FROM and TO paths must correspond to valid devicespecs. For N: devicespecs, the directory prefix is utilized.

Since the NCOPY command talks directly to the #FujiNet over SIO, it attempts to send and receive data with N: file systems in large 16 kilobyte chunks, making file copies marginally faster. As with the other N utilities, NDEV does not need to be present in memory.

To copy from a CIO device, such as D, to an N: device, use the following parameters:

D[x]:FROM.FIL,N[x]:<TO_PATH>

For example:

D1:FROG.EXE,N:TNFS://HOMESERVER/GAMES/FROG.EXE

To copy from an N: device to a CIO device, such as D:, use the following parameters:

N[x]:<FROM_PATH>,D[x]:TO.FIL

For example: assume that N:'s prefix is set to FTP://FTP.PIGWA.NET/stuff/collections/holmes cd/Holmes 2/Atari Archives/Antic Files/88/:

N:FROG.EXE,D1:FROG.EXE

You can copy from one N: device to another:

N[x]:<FROM_PATH>,N[x]:<TO_PATH>

For example, with NCD setting the following two devices:

NCD N1:FTP://FTP.PIGWA.NET/pub/collections/holmes cd/Holmes 2/Atari Archives/Antic Files/88/
NCD N2:HTTP://MYHOMESERVER/games/

You can copy FROG.EXE from one to the other:

NCOPY N1:FROG.EXE,N2:FROG.EXE

Currently, the NCOPY utility does not support wildcards. They will be supported in the future.

NDEL can be used to delete files from network resources. Like the other N: tools, it can be used without NDEV being present, as it talks directly to the #FujiNet over SIO.

As with the other N: tools, if a parameter is not specified, one is asked for interactively.

WARNING: Unlike DOS, NDEL does not prompt to confirm any deletion! USE WITH CARE!

NDEL's only parameter is an N: devicespec pointing to the file to be deleted:

NDEL <N_DEVICESPEC>

For example:

NDEL N:HTTP://HOMESERVER/BLAH.TXT

This would delete the file BLAH.TXT from the HTTP server HOMESERVER.

As with all other tools, if N: isn't specified, or a unit number isn't specified, "N1:" is assumed.

NREN is used to rename a file on a network filesystem. The original and new filenames are specified, separated by a comma.

Like all of the other N: tools, NDEV is not required to be present.

NREN [N[x]]:<OLD>,<NEW>

For example:

D1:NREN N1:TNFS://TMA-1/FOO.TXT,BAR.TXT

This would rename FOO.TXT to BAR.TXT on the TNFS server called TMA-1.

NOTE: This tool isn't written yet, but will be soon.

This tool will allow you to load a binary file from an N: device and execute it. Its only parameter is a valid N: devicespec to the desired binary file.

Since N: is a CIO device, it can be used in BASIC, once the NDEV handler is loaded. It can be used not only to load and save BASIC files to network filesystems, but also to open data files on network filesystems, and even directly open IOCB channels to TCP or UDP network sockets.

BASIC can support devicespecs up to 128 characters in length, and thus it is easy to specify a full N: devicespec without needing to utilize NCD or other tools.

Loading BASIC programs from the network is simple. If no directory prefix is specified:

RUN "N:HTTP://ATARI-APPS.IRATA.ONLINE/BLACKJACK.BAS" 

would load BLACKJACK.BAS from ATARI-APPS.IRATA.ONLINE over HTTP.

BASIC can also fully utilize the directory prefix, making it easier to load programs. XIO call 44 is provided for this purpose, matching the same call in MyDOS and SpartaDOS:

READY
XIO 44,#1,0,0,"N:HTTP://ATARI-APPS.IRATA.ONLINE/"

READY
RUN "N:BLACKJACK.BAS"

This works irrespective of the currently loaded DOS.

Saving BASIC programs can be done in precisely the same way as with a disk:

SAVE "N:TNFS://HOMESERVER/PEWPEW.BAS"

Using a prefix:

READY
XIO 44,#1,0,0,"N:TNFS://HOMESERVER/"

READY
SAVE "N:PEWPEW.BAS"

Since the N: device exposes a full CIO device, it is possible to use all the available CIO commands to interact with files, directories, and TCP/IP sockets on the network.