﻿Welcome to the AI-WX Weather Door Installation Document. I'll try to cover all
the bases here, but if you have any questions, please feel free to ask. I can 
be reached at the following locations:
	  
	Support BBS:	firesidebbs.com telnet port: 23231
	Email:			firesidebbs@gmail.com
	Internet:		firesidebbs.com

This document is broken down into the following sections:

	Initial Install:	Getting the door up and running.
	  Configuration:	Setting up the door for your BBS.
	 Door Drop File:	Pointing the door to your door32.sys drop file.
Custom Menu Options:	Make AI-WX your own with unlimited custimazations
       Registration:	Registering the door.
		   Appendix:	Complete list of custom command line parameters.
		     Thanks:	Thanking the beta testers. 


Begin:
	Initial Windows Installation:
		1. Unzip the contents of the AI-WX .ZIP file into a folder on your
		BBS.

		2. Locate the LWSWeather.exe executable file. This is the main program
		file you'll execute from the BBS.

	Initial Linux Installation:
		1. Unzip the contents of the AI- .ZIP file into a directory on 
		your BBS.
		2. Locate the wxdoor file. This is the main program file you'll execute
		from the BBS.
		3. IMPORTANT: Make the wxdoor file executable by typing chmod +x wxdoor.

	Configuration:
		1. Edit the lwsdoor.ini file. The .ini file is well commented and 
		should be self-explanatory.

		2. Set the BBSName, EmailAddress, UseSixelRadar, BBSDomainName and 
		BBSNameSuffix at the very least.

		3. If you have registered the door, make sure the BBSName and RegKey
		match your registration info exactly as they are case sensitive.

	Door Drop File:
		1. Point the door to your system's door32.sys drop file. This is BBS 
		software dependent, but	a few examples here that should help you get 
		started.

		Synchronet Windows: LWSWeather.exe -D%n
		Synchronet Linux: wxdoor -D%n

		or

		Mystic Windows: LWSWeather.exe -D%P
		Mystic Linux: ./wxdoor -D%P	

	Custom Menu Options:
		1. Beginning in version 1.2, you can now run each menu option that
		is available inside the door's Main Menu independently. This means 
		you can add custom menu options to your BBS that will run the door
		with the specific menu option you want.

		These options run outside of the usual Ai-WX door's program flow.
		This is a great feature for BBS's that want to add a custom menu option
		to run the door with the "Radar" menu option, for example.

		2. To add a custom menu option, you'll need to add a line to your BBS's
		menu file that will run the door with the specific menu option you 
		want. Once the option is displayed to the user, the door exits back to
		the BBS menu it was called from. This makes it possible to create a 
		completely BBS centric custom experience as if the user never leaves
		the BBS itself and enters a door. The door will run with the menu
		option you specify and then return to the BBS menu it was called from.
		
		3. Here is an example of how you would add a custom menu option to
		your BBS's menu file that would run	the door with the "Radar" menu
		option:
		
		Synchronet Windows: LWSWeather.exe -D%n -R3 -I%i
		Synchronet Linux: wxdoor -D%n -R3 -I%i

		or

		Mystic Windows: LWSWeather.exe -D%P -R3 -I%4
		Mystic Linux: ./wxdoor -D%P -R3 -I%4		

		Let's break this down and see what's happening here. 
		
		The LWSWeather.exe or wxdoor file is the door file, -D is the door's
		command line parameter for passing in the path to the BBS's door32.sys
		drop file.
		
		-Rx is the door's command line parameter for passing in the "Radar" 
		function, where x is a number from 1-4 and is the zoom level of the 
		radar images.
		
		-I is the door's command line parameter for passing	in the user's IP
		address. This is important because the door needs to know the user's
		location to display weather data based on their location. The user's
		IP address is geocoded to get the latitude and longitude of the user's
		location for the weather APIs.
		
		The %P,%n, %4 and %i are BBS software specific variables that will be
		replaced with the path to the BBS's door32.sys drop file and the 
		user's IP address respectively. You'll need to check your BBS's	
		documentation for the correct variables to use in your BBS's menu 
		file if not using Synchronet or Mystic.

		So with this example command line, the door will run with the "Radar"
		menu option and display the radar for the user's location. The door
		then return to the BBS menu it was called from when the user quits
		viewing the radar. This is a great way to add custom weather related
		menu options to your BBS that will run the door with the specific
		weather option you want.

		6. Custom menu options include "Current Conditions", "Forecast", 
		"Alerts", "Radar" and "Trends" just to name a few. This is a great 
		way to add a customized weather experience for your user to your BBS
		that will run the door with the specific AI-WX option from your BBS's 
		menu system.

		7. There is a complete list of command line parameters/menu options
		in the appendix at the end of this document.

	Registration:
		1. AI-WX is being released under the old school Shareware/Buy Me a 
		Coffee concept. In fact, it's free to use, but if you like the door
		and want to support the author, you can do so by visiting 
		firesidebbs.com and clicking on the Buy Me a Coffee link. 
		
		Although it is free to use, you must register the door to remove the
		registration screens and if you plan on using it for more than 30 day,
		you really should register it. It's cheaper than a fancy cup of coffee
		and it would be greatly appreciated. I must also mention that piracy
		is a crime and is not cool. ;)

	Appendix:
		1. Command Line Parameters:
			-D  Path to the BBS's door32.sys drop file. This is the only 
			required parameter. Other parameters are for custom menu options.
			If -D is used by itself, the door will run with the normal Intro,
			Search then Main Menu flow.
			
			FUNCTIONS: The following commandline parameters are used with the
			custom menu	options that execute and then return to the BBS menu 
			they were called from. Only one of these can be used at a time.

			-A  Alerts, falls back to Seven Day Forecast if the IP is not in 
			the US (Alerts are from the US National Weather Service, so only
			available in the United States).

			-E  Extend Forecast, used with -I or -X -Y -Z. This also falls 
			back to Seven Day Forecast if the IP is not in the US.

			-S  Search, it drops the user into the search screen, so no need
			to pass -I or any static lat/lon coordinates as they will search
			for the location.

			-Q  Drops straight to the door's Main Menu at the location passed
			in, use with either the -I or -X -Y -Z paramters below.

			-Rx  Radar where the x is a number from 1-4 for the radar zoom 
			level, the higher the number the higher the zoom level, used 
			with -I or -X -Y -Z. AI-WX takes advantage of Sixel graphics to 
			display high resolution radar images under terminals that support 
			it. Currently, SyncTerm and ICYTerm are the two that I know of that
			support Sixel graphics. If the user's terminal does not support 
			Sixel graphics, the door will fall back to an ANSI text based radar
			display, which in itself is pretty impressive.			

			-F  Abbreviated 7 Day Forecast, used with -I or -X -Y -Z

			-U  Current Conditions, used with -I or -X -Y -Z

			-T  Temp Trends, used with -I or -X -Y -Z

			-P  Precip Trends, used with -I or -X -Y -Z

			-V  Precip Amount, used with -I or -X -Y -Z

			LOCATION: The following commandline parameters are used to pass 
			location information to AI-WX for weather data related to the
			caller's location.

			-I is used with the the BBS's ip address parameter. As examples, 
			you would do -I%i for Synchronet or -I%4 for Mystic to have the
			BBS software pass in the user's ip address so it can be geocoded
			to their location. -I cannot be combined with -X, -Y and -Z below.

			-X  Pass in the latitude for a static location

			-Y  Pass in the longitude for a static location

			-Z  Pass in the Title that is displayed for the static location 
			(used with -X and -Y only).

			The X, Y and Z parameters must be used together as they make 
			the parameter package needed to pass in a static location. You 
			can Google for the lat/lon of any location. These cannot be 
			combined with -I.

			NOTE: It is best to wrap -X, -Y and -Z in double quotes in case
			there are any spaces or special characters. 					
			
			So something like...

			Synchronet Windows:
		LWSWeather -D%n  -U "-X28.396837" "-Y-80.605659" "-ZCape Canaveral, FL" 
			Synchronet Linux:
		wxdoor -D%n  -U "-X28.396837" "-Y-80.605659" "-ZCape Canaveral, FL"  

			or

			Mystic Windows:
		LWSWeather -D%P  -U "-X28.396837" "-Y-80.605659" "-ZCape Canaveral, FL"
			Mystic Linux:
		./wxdoor -D%P  -U "-X28.396837" "-Y-80.605659" "-ZCape Canaveral, FL"

			...would display the Current Conditions (-U) at Cape Canaveral and
			then exit back to your bbs menu. Notice that -X, -Y and -Z are all
			wrapped in double quotes.

			MEASUREMENTS: The following parameters determines how AI-WX will
			display the weather data. By default the data is displayed in 
			either imperial or metric based on the location that the data is
			for. You can force either imperial or metric with this parameter.

			-M  this is for denoting if the measurements shown should be 
			displayed in metric. If not present, then imperial units are used.
			Use with -X and -Y, not needed with -I.

			RADAR FLOW RATE: The ANSI and Sixel radar/infrared data flows
			out the IO at a pretty good clip. This parameter allows you to
			increase/decrease the pause in between radar frames to allow
			the IO buffer to clear out before the next frame. This parameter
			is optional and should not be needed except in rare cases where
			your bbs may have a slow connection or you are presenting the
			door to the user via fTelnet or something similar. In the case of
			fTelnet, then something like -W1500 works well with my setup.

			-Wxxxx introduces a pause between radar/infrared animation frames.
			Replace the xxxx with the number of milliseconds to pause between
			frames. 1000 milliseconds equals 1 second. Be VERY careful with
			this parameter. It can have an extremely adverse effect on the user 
			experience. Set too low and it can overflow the user's terminal
			and make the radar menu options seem unresponsive, set too high
			and the radar will creep along very slowly and there will be a
			long pause between the caller's menu selection and the door
			responding. This is best left off of the parameters used to call
			the door except in rare instances such as when displaying the door
			via fTelnet. In which case a setting of -W1500 seems to work well
			at firesidebbs.com.	

		2. Synchronet Specific Help:
			%n is the Synchronet specific parameter for passing in the path to
			the BBS's door32.sys drop file.

			%i is the Synchronet specific parameter for passing in the user's 
			IP address.
			
			Synchronet LINUX:
			On the Linux version of Synchronet, you'll need to set the 
			I/O Method to Standard as this is a native linux application and a
			fossil driver or Socket is not required. You'll also want to set
			Native Executable to Yes. You'll also want to set 
			Use Lowercase Filenames	to Yes.

			1: Name                        AI-WX Weather Door
			2: Internal Code               AI-WXWEATHER
			3: Start-up Directory          ../xtrn/weather/
			4: Command Line                wxdoor -D%n
			5: Clean-up Command Line      
			6: Execution Cost              None
			7: Access Requirements        
			8: Execution Requirements    
			9: Multiple Concurrent Users   Yes
			10: I/O Method                 Standard
			11: Native Executable/Script   Yes
			12: Use Shell to Execute       Yes
			13: Modify User Data           No
			14: Execute on Event           No (or "Logon" or "Logon, Only", it is up to you)
			15: Pause After Execution      No
			16: Disable Local Display      No
			16: BBS Drop File Type         door32.sys
			17: Place Drop File In         Node Directory
			18: Time Options...


			Synchronet WINDOWS:
			On the Windows version of Synchronet, you'll need to set the 
			I/O Method to Socket and the Native Executable to Yes.

			1: Name                        AI-WX Weather Door
			2: Internal Code               AI-WXWEATHER
			3: Start-up Directory          ../xtrn/weather/
			4: Command Line                lwsweather.exe -D%n
			5: Clean-up Command Line      
			6: Execution Cost              None
			7: Access Requirements        
			8: Execution Requirements    
			9: Multiple Concurrent Users   Yes
			10: I/O Method                 Socket
			11: Native Executable/Script   Yes
			12: Use Shell to Execute       No
			13: Modify User Data           No
			14: Execute on Event           No (or "Logon" or "Logon, Only", it is up to you)
			15: Pause After Execution      No
			16: Disable Local Display      No
			16: BBS Drop File Type         door32.sys
			17: Place Drop File In         Node Directory
			18: Time Options...

			You'll want to set the BBS Drop File Type to door32.sys for 
			both Windows and Linux.

			Some sysops have had to install a package named terminfo or 
			termcap to get the door to look right under Synchronet. terminfo
			or termcap must be installed when installing Synchronet	as 
			documented on the Synchronet wiki found at
			(https://wiki.synchro.net/install:nix:termcaps). This should
			have been installed as part of your original Synchronet install, 
			but if not, you'll need to install it for AI-WX and probably 
			several other doors to work correctly.

		3. Mystic Specific Help:
			%P is the Mystic specific parameter for passing in the path to 
			the BBS's door32.sys drop file. Use this with 
			the -D parameter, -D%P.

			%4 is the Mystic specific parameter for passing in the user's
			IP address. Use this with the -I parameter, -I%4.

			On Mystic you'll want to use the Menu Action Type of (D3) Exec 
			DOOR32 Program. Then place the ./ in front of the wxdoor file as
			in ./<path to>/wxdoor for the program to be executed by the BBS.
			Also, don't forget to chmod +x the wxdoor file to make it 
			executable.
			
		4. WWIV Specific Help:
			If you are using WWIV, I've found that some Linux systems require
			that you add the following to your command line. Under WWIV 
			(and possibly others), you may need to add the following
			to the front of your chain's (door) command line. For example, 
			instead of the command line just being...

				./chains/weather/wxdoor -D%E

			you would instead enter...

				export TERM=pcansi && ./chains/weather/wxdoor -D%E

		5. Other BBS Software:
			If you are using other BBS software, you'll need to check your
			BBS's documentation for the correct parameters to use for the
			path to the door32.sys drop file and the user's IP address.

	Thanks:
			I would like to thank my beta testers, who contributed many 
			helpful suggestions and subjected their systems to a new door 
			without hesitation. Kudos to Gamgee, Shurato and Solaris for
			making the door much better than it would have been otherwise.
			Your efforts are very much appreciated.

	Disclaimer:
			THIS SOFTWARE IS PROVIDED "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
			INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY,
			FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT, ARE DISCLAIMED.  IN NO
			EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
			EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT
			OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
			INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
			CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
			IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY
			OF SUCH DAMAGE.

End:
	That's it! You should be up and running with the AI-WX Weather Door. 
	If you have any questions, please feel free to ask. My info is listed
	up top and I'm always hanging out in some of the BBS message networks. 
	And other Sysops are always willing to help too if you get stuck. I hope
	you enjoy the AI-WX Weather door and find it useful.

	Vincent Jacobs aka Lonewolf
	Lone Wolf Software Copyright (C) 2025
			



