@database Poseidon-Manual @author "Chris Hodges" @$VER: Poseidon V1.12 (14-Dez-03) @toc main @node main "Poseidon USB Stack Manual" @{b}Welcome to the @{fg shine} __ __ @{fg text} V/\\V. @{fg shine}/\\@{fg text} @{fg shine}|" | |" |@{fg text} mMMnw, @{fg shine}|| []@{fg text} @{fg shine}| | | |@{fg text} (o o)W @{fg shine}() || ||@{fg text} @{fg shine}|__|_|_"|@{fg text} | / |Mw @{fg shine}|| ||//@{fg text} @{fg shine}(" " \\|@{fg text} \\ -'_/mw @{fg shine}\\\\||/@{fg text} @{fg shine} \\______)@{fg text} ~%%/WM" @{fg shine}\\||@{fg text} _____ ___ @{fg shine}______@{fg text} _____ __ _____ ___ __ __/~~__ ~~\\ _@{fg shine}||@{fg text} |"(" \\()/\\" \\ ()@{fg shine}/"_ )@{fg text}|"(___) ) )|"(" \\ ()/\\" \\(__)/" ) /" ) " \\ /_)O | ) )/" \\ \\ @{fg shine}(_/"\\__/@{fg text} | )_ ( ( | )_ ) /" \\ \\ / /|/ / ·\\ \\/ ,@{fg shine}|@{fg text}O | (___/( (_\\__) @{fg shine}_\\ \\_@{fg text} | (__) ) )| (__) |( (_\\__)/ /"/ / |\\ '_@{fg shine}|@{fg text}O | | _ \\ / / @{fg shine}/" \\_/ )@{fg text} | ")__ ( ( | )" ) \\ / // /|/ / . .|/\\__/ @{fg shine}||@{fg text} |__| (_) \\/__/ @{fg shine}(______/@{fg text} |_(___) )_)|_(___/ . \\/__/(__/ (__/ .:.:| @{fg shine}||@{fg text} @{fg shine} _____ @{fg text} @{fg shine}|" __ \\ @{fg text} Poseidon -- The divine USB stack for Amiga computers @{fg shine}| (__) )@{fg text} Version: 2.2 (14.12.03) @{fg shine}| __ ( @{fg text} Designed and written by Chris Hodges. @{fg shine}|"(__) )@{fg text} @{fg shine}|_____/ @{fg text} Copyright ©2002-2003 @{" Chris Hodges " link contactaddress}. All rights reserved.@{ub} WARNING: @{b}Read @{" this " link legalstuff} first before using this software!@{ub} --------------------------------------------------------------------------- @{" Legal Issue " link legalstuff} @{" Demo Version Limitations " link demoversion} @{" Introduction " link introduction} @{" Requirements " link requirements} @{" Installation " link installation} @{" Using the Poseidon Stack " link usingposeidon} @{" Using Trident " link usingtrident} @{" Class Drivers " link classdrivers} @{" Hardware Drivers " link hardwaredrivers} @{" Shell Tools " link shelltools} @{" Known Bugs " link bugs} @{" FrequentlyAskedQuestions " link faq} @{" The Future " link future} @{" Developer Docs " link devdocs} @{" Acknowledgements " link thanks} @{" Contacting the Author " link contactaddress} @{" Version History " link history} @endnode @node legalstuff "Legal Stuff..." @{b}---------------------------------------------------------------------------@{ub} @{b}@{fg highlight}Copyright notice@{fg text}@{ub} @{b}---------------------------------------------------------------------------@{ub} The "Poseidon USB Stack" software (the main library, the class drivers, included hardware drivers, Trident, additional tools and other pieces of software included in this package) and documentation is written and Copyright 2002 by Chris Hodges. All rights reserved. No parts of this program or documentation may be altered by any means (this includes editing, modifying, reprogramming, extracting, crunching, resourcing etc.) except archiving. It is especially illegal to redistribute, modify or create a keyfile or any other software that will enable the features in Poseidon which are disabled without licence or personal keyfile. The Application Programmers Interface (API) of the "Poseidon USB Stack" is protected by the laws of intellectual property. Software, that allows the use of class drivers or hardware drivers without using the whole Poseidon software itself, violates this licence. Names and products used in this manual may be registered trademarks or products of the corresponding company, even if they are used in this manual without further notice. @{b}---------------------------------------------------------------------------@{ub} @{b}@{fg highlight}Disclaimer@{fg text}@{ub} @{b}---------------------------------------------------------------------------@{ub} This software has been proven stable in everyday use. The author is in no way liable for any loss of data, damages to software or hardware, impacts on the health of people worldwide or on your love life, that may result directly or indirectly from use of this program. The author reserves the right to make changes to this software or documentation without notice. Any modifications to this software and/or a keyfile may yield to unexpected results. The author is not liable for any damage done by a modified version, neither by incident nor on purpose! @{b}---------------------------------------------------------------------------@{ub} @{b}@{fg highlight}Distribution@{fg text}@{ub} @{b}---------------------------------------------------------------------------@{ub} This software is @{b}not freely distributable@{ub} unless explicitly noted. Distribution rights remain at the author. It may explictly not be included in commercial software packages without written permission from the author. Again: None of the files in this package may be modified or left out or distributed with other products without written permission from the author. No unrelated files may be added to any archive containing this program. @{b}---------------------------------------------------------------------------@{ub} @{b}@{fg highlight}Demo Version@{fg text}@{ub} @{b}---------------------------------------------------------------------------@{ub} If this software package explicitly has been marked as a unlicenced demo version containing no keyfile, this software may be tested up to 30 days before you have to deinstall it and acquire a legal keyfile. The demo version is freely distributable, if no fee is charged, it is not included in a commercial product and it is not stated otherwise. @{b}---------------------------------------------------------------------------@{ub} @{b}@{fg highlight}Registered Software License Agreement@{fg text}@{ub} @{b}---------------------------------------------------------------------------@{ub} The author of this software will grant the Licensee a limited, nonexclusive right to use the program "Poseidon USB Stack" and its associated files on a single machine. The producer will hand out a special identification file called the keyfile to the Licensee. This keyfile will enable the Licensee to fully use this software package according to the terms of this license. The keyfile is strictly for personal use by the Licensee only. You may not duplicate, distribute, hire or sell a keyfile. Any disclosure of the keyfile will invalidate the license and the keyfile itself. The Licensee must ensure that the keyfile will not disclosed by accient (e.g. enclosed in another file, especially configuration files). The Licensee will be held liable of any damage arising out of the disclosure of the keyfile. The product is provided as is without warranty of any kind, either expressed or implied, statutory or otherwise, including without limitation any implied warranties of non-infringement, merchantability and fitness for a particular purpose. The entire risk as to use, results and performance of the product is assumed by you and should the product prove to be defective, you assume the entire cost of all necessary servicing, repair or other remediation. In no event shall the producer of this product or its resellers be liable for any property damage, personal injury, loss of use or other indirect, incidental or consequential damages, including without limitation, any damages for lost profits, business interruption or data which may be lost or rendered inaccurate, even if I have been advised of the possibility of such damages. This agreement shall exclusively be governed by the laws of the Federal Republic of Germany. @{b}@{fg highlight}By copying, distributing and/or using this software you indicate your acceptance of the above rules.@{fg text}@{ub} @endnode @node demoversion "Demo Version Limitations" @{b}--------------------------------------------------------------------------- Demo Version Limitations ---------------------------------------------------------------------------@{ub} Huge efforts were made to write the Poseidon USB Stack. These efforts were largely supported by the manufacturer and vendor of the Highway, Subway and Algor USB cards E3B and also by bPlan, delivering several pieces USB hardware and large amounts of chocolate. This software therefore is sold along the Highway, Subway and Algor USB cards and included for the onboard USB chipset of the Pegasos. In my opinion it would be pretty unfair to give this software away for free to other USB board or PCI bridge manufacturers (as they would only need to write a hardware driver for the publically documented hardware interface to benefit from all the class drivers and other software included). However, it also would be unfair to demand from each manufacturer to licence the software package, when there is some other software included already. Therefore, Poseidon has to be registered by acquiring a single user licence, whenever there is no OEM licence for a hardware driver. This keyfile is not very expensive (see below) in my opinion. If the licence is missing, Poseidon will operate in demo mode. In this mode, the stack can be checked for functionality, but will stop working after a short time (you will start getting "response timeout" error messages). @{b}ATTENTION: Pegasos Users and owners of the Highway, Subway and Algor boards do NOT need to register!@{ub} @{b}Please note well, that it is now possible to buy a Poseidon licence from IOSpirit (http://www.iospirit.com) aswell. Using the online registration it is also possible to use credit card payment.@{ub} @{b}--------------------------------------------------------------------------- Registration Form ---------------------------------------------------------------------------@{ub} To: Chris Hodges Kennedystraße 8 D-82178 Puchheim Germany To: poseidon@platon42.de (in case of bank transfer and email) YES, I want to buy a single user licence for Poseidon. I have enclosed the licence fee as (please tick): O Cash (EUR 25) O Cheque (inside Germany: EUR 23) O Cheque (outside Germany: EUR 27) O Bank Transfer (EUR 23) to Account : 359 68 63 BLZ : 700 530 70 Bank : Sparkasse Fürstenfeldbruck IBAN : DE61 7005 3070 0003 5968 63 SWIFT-BIC: BYLADEM1FFB Please fill out the following lines: Company: ______________________________________ Name: ______________________________________ Street: ______________________________________ PC, City: ______________________________________ Country: ______________________________________ E-Mail: ______________________________________ Phone #: ______________________________________ The keyfile will be sent to the above address via: O E-Mail (no shipping costs) O Disk (add EUR 5 for shipping costs) This is optional: USB Board: ______________________________________ Kickstart: ______________________________________ Computer: ______________________________________ (CPU, RAM Add-ons) ______________________________________ How do you rate this Software: very good-1 2 3 4 5 6-very poor features O O O O O O installation O O O O O O docs O O O O O O price/value O O O O O O support O O O O O O fun O O O O O O Comments, suggestions, new ideas, bugs...: ____________________________________________________ ____________________________________________________ ____________________________________________________ ____________________________________________________ By filling out and sending this registration form you have accepted the licence agreements. _________________ _____________________________ (City, Date) (Signature) @endnode @node introduction "Introduction..." @{b}--------------------------------------------------------------------------- Introduction to Poseidon ---------------------------------------------------------------------------@{ub} The Poseidon USB Stack is a software solution that unleashes the possibilities of the Universal Serial Bus (USB) and the devices with USB interface, ranging from mice, keyboards, tablets, joysticks, printers, scanners, webcams, digicams, flash card readers, zip drives, floppy disk drives, harddisks, memory sticks, ethernet adapters, scanners and audio adapters to less common things like power supplies, GPS location devices or finger print readers. It is intended to be a solution for all systems. Poseidon has a modular design that fits into the AmigaOS environment very neatly. It is no port of an existing system (like the Linux USB stack), but has been created with the unique features of AmigaOS in mind that make the operation system so efficient. There is no limit to which USB controller hardware can be used, as long as a hardware driver exists -- and the device driver API is public and well documented. Poseidon is being shipped as OEM with and licenced for the Highway/Algor Zorro II and the Subway clockport USB board. Poseidon uses external class libraries to enable software support for standard USB device types. This ensures the plug & play key features -- just connect the device and it works immediately. The class driver specification is also very easy to understand and to program. For example the first working version of the mouse driver was written within a few hours. @{" Click here for a list of included class drivers " link classdrivers}. For application programmers, it is also possible to talk with certain USB devices directly without having to go through the class interface, although it is recommended that standard devices drivers should use the class interface. Trident, a complete MUI-based frontend for configuration and startup is provided for more comfortable usage and view on the connected USB devices. However, the GUI is not required for operation. Two shell commands are enough to load up the stack. Poseidon can be made reset-resident using its @{" RomTags " link romtags}. It can therefore enabled very early at boot time, especially to use the USB mouse or keyboard inside the boot menu. However, due to the boot menu of <= OS3.9 using hardware hacking to check for the two mouse buttons, a @{" patch " link bootmenu} must be applied to allow USB mice to be able to invoke the menu. Otherwise you still have to use the normal mouse buttons to reach the boot menu. @{b}--------------------------------------------------------------------------- Introduction to USB ---------------------------------------------------------------------------@{ub} The Universal Serial Bus (USB) was first introduced in the PC consumer market in 1996 by the USB consortium (Compac, Intel, Microsoft and NEC). USB1.0/1.1 was targeted for the low and mid cost market and used raw transfer rates of 1.5Mbit/sec (Lowspeed) and 12Mbit/sec (Fullspeed). Later, to compete with FireWire, a highspeed mode with 480Mbit/sec raw data rate was introduced with USB2.0. USB uses a tree-like structure. The root of this tree is the host computer's root hub. Each USB device can be connected to one of these hub ports. Using an external hub which needs to be connected to a downstream port of a hub itself, the structure can be branched further. USB devices have two ways to get the current they require: they are either bus powered (i.e. the power is distributed by the hub they are connected to) or self-powered (i.e. they come with their own power supply). There are certain limitations to bus powered devices. They may not drain more than 500mA from the hub they're connected to. This might sound enough, but remember that external bus powered hubs will only have 0.5A for all downstream ports themselves. Use self-powered hubs and devices whenever possible. Maybe the next part gets a bit technical, if you want to skip it, just go ahead. These devices can support multiple configurations. I haven't yet seen one with more than one configuration. The configuration contains one or more interfaces of possibly different classes. Compound devices, i.e. a wireless keyboard/mouse combo, may contain an interface for the mouse and another one for the keyboard. USB defines a set of standard classes for certain applications. However, vendors are (unfortunately) free to implement their own protocol. Interfaces may have alternative settings which are mutual exclusive (i.e. a printer that can be driven in either bidirectional or unidirection mode). There are standard classes and subclasses defined for USB both on device and on interface level. So a device may be of no special class, but have multiple interfaces, which may belong to different clases. Or a keyboard can have two interfaces, one for the normal keys, and a second one for special application keys. Each interface has usually one or more endpoints. These endpoints allow to send or receive data. Now it really gets technical. There are four types of endpoints, and therefore also four different transfer types. Control transfers are short (normally 8 byte packets), bidirectional transfers for setting up or controlling the device. Each device must at least have endpoint 0, which is always a control endpoint. Interrupt transfers are short (1-8 byte packets), periodical, but reliable transfers. These are normally used to poll for events (like mouse events or key strokes). Bulk transfers are medium sized (up to 64 byte packets), bursty and reliable transfers, but without guaranteed bandwidth (i.e. the transfer may take a long time to complete if the bus is busy). Isochonous transfers are normally large (up to 1023 byte packets), time critical transfers, but without error checking. These are normally used for realtime audio or video data. @endnode @node requirements "Requirements..." @{b}--------------------------------------------------------------------------- Requirements ---------------------------------------------------------------------------@{ub} @{b}Requirements:@{ub} - Kick 3.0 (V39) or higher - MC68020 or higher - About 200KB free memory - An USB hardware controller and its hardware driver - Devices with USB interface ;-) - MUI for the Trident GUI or - MorphOS 0.4 (V50) or higher - PPC603e or higher - About 300KB free memory - An USB hardware controller and its hardware driver - Devices with USB interface ;-) - MUI for the Trident GUI @{b}Recommended:@{ub} - Kick 3.1 (V40) or higher - MC68040 or higher - About 1MB free memory - A Highway/Subway USB board - USB devices that are sure to be compliant with the USB standard ;-) or - Pegasos with MorphOS - PPC604 or higher - About 1MB free memory - Onboard USB controller - USB devices that are sure to be compliant with the USB standard ;-) @{b}Developed on:@{ub} - A4000TE/60, 100MB, 40GB HD, CDR, ZIP, CV64, FliFix, Highway, Subway, Algor, Unity, MelodyPro, Silversurfer. @endnode @node installation "How to install this great software..." @{b}--------------------------------------------------------------------------- Installation ---------------------------------------------------------------------------@{ub} Please use the included installer script for installing the Poseidon software. For the expert users, the files can also be copied onto your system manually. - Copy Libs/poseidon.library TO LIBS: This is the main library containing the stack itself. - Copy Devs/USBHardware/#? TO DEVS:USBHardware These are the included @{" hardware device drivers " link hardwaredrivers}. - Copy Classes/USB/#? TO SYS:Classes/USB The supplied @{" class drivers " link classdrivers}. DO NOT COPY OTHER FILES INTO THIS DIRECTORY, such as library files or device drivers. This will pretty certainly cause a crash at the class driver scan. - Copy Tools/#? TO C: - @{" AddUSBClasses " link addusbclasses} - @{" AddUSBHardware " link addusbhardware} - @{" PsdErrorLog " link psderrorlog} - @{" PsdDevLister " link psddevlister} - @{" PenCamTool " link pencamtool} - Copy Trident#? TO SYS:Prefs @{" Trident " link usingtrident} is the GUI for Poseidon. Requires MUI to run. Run Trident at least once to save the config file in ENVARC:PsdStackloader. - If you want Poseidon to start automatically on booting, add the line "ENVARC:PsdStackloader" to your S:User-Startup file. - Install LoadModule from the archive in the "Extra" folder, if you don't already have a @{" LoadModule " link loadmodule} program in your C:-directory. - Copy PsdRomTag#? TO SYS:Utilities This is a small shell script that will automatically install all required files residently as @{" RomTags " link romtags}. - Copy Devs/input.device TO DEVS: Add a line "LoadModule DEVS:input.device QUIET" to your Startup-Sequence, preferably just before SetPatch. If you are using THOR's LoadModule program, use "LoadModule DEVS:input.device NOREBOOT QUIET" instead. - Copy Storage/#? TO SYS:Storage There's an example DOSDriver entry for @{" mass storage devices " link massstorage.class}. @endnode @node usingposeidon "Using the Poseidon..." @{b}--------------------------------------------------------------------------- Using the Poseidon Stack ---------------------------------------------------------------------------@{ub} Poseidon mainly needs three things to start: A) At least one @{" hardware driver " link hardwaredrivers} B) @{" Class drivers " link classdrivers} for the USB devices attached C) The @{" configuration file " link psdstackloader} Normally, running the PsdStackloader will automatically also load up the hardware driver and class drivers, if you entered these in the @{" Trident " link usingtrident} prefs. Once these three things have been installed, USB devices are ready for use. Just plug in your USB devices into the downstream ports of your root hub. Mice, keyboards and printers will be usable immediately, mass storage devices need to be mounted first (see @{" class description " link massstorage.class}). @endnode @node usingtrident "Using Trident..." @{b}--------------------------------------------------------------------------- Using Trident ---------------------------------------------------------------------------@{ub} Trident is the graphical user interface (GUI) to configure the stack. Trident requires MUI to run. There are five panels: @{" General " link tridentgeneral} @{" Hardware " link tridenthardware} @{" Devices " link tridentdevices} @{" Classes " link tridentclasses} @{" Config " link tridentconfig} @{b}--------------------------------------------------------------------------- Information Box ---------------------------------------------------------------------------@{ub} In the lower part of the window, the error and notification messages are listed. All information flow between the user and the stack itself can be seen in this box. Whenever you plug in an USB device, you'll get a message, and when you unplug it again, it is also shown in this box. You can change which kind of messages you want to see using the 'information level' cycle gadget. To remove all current messages from memory, click on the 'flush error messages' gadget. You can also disable the generation of messages in the @{" Config panel " link tridentconfig}. @{b}--------------------------------------------------------------------------- Online / Offline ---------------------------------------------------------------------------@{ub} To halt the stack and power down the downstream devices, just click on 'Offline', which will effectively remove the hardware drivers from the stack. To restart the stack, use the 'Online' switch. @{b}--------------------------------------------------------------------------- Configuration ---------------------------------------------------------------------------@{ub} Trident automatically loads up the existing configuration and launches the stack on the first start. The current configuration can be stored to disk using the 'Save' button to the lower right of the main window or the 'Save' or 'Save as...' menu items in the 'Settings' menu. The config file itself is an executable (see @{" PsdStackLoader " link psdstackloader}). To reload a previously saved configuration select the 'Load' menu item. @{b}--------------------------------------------------------------------------- Registration / Licencing ---------------------------------------------------------------------------@{ub} If you have acquired a legal Poseidon keyfile, you can activate it by selecting the "Inject keyfile..." menu item. Note well that after this step the keyfile is also included in any configuration file you save, so be especially careful not to disclose these files. The licence information storaged in the keyfile will be displayed in the hardware driver information window. @endnode @node tridentgeneral "Trident General Panel" @{b}--------------------------------------------------------------------------- Trident General Panel ---------------------------------------------------------------------------@{ub} Not much to see here except for a nice Poseidon logo and some very fine lyrics of Aimee Mann songs. Be sure to get her latest CD "Lost In Space". It the best CD EVER :) @endnode @node tridenthardware "Trident Hardware Panel" @{b}--------------------------------------------------------------------------- Trident Hardware Panel ---------------------------------------------------------------------------@{ub} This is where you add or remove your @{" hardware drivers " link hardwaredrivers}. I hope this is straight forward, and I do not need to add much information here. Double clicking on the hardware driver line or pressing the Info button will open an additional information window, showing more detailed information on the hardware driver. Also, this window will contain information on the licence installed. Some USB hardware drivers require multiple units to be added so that all USB ports will work. @endnode @node tridentdevices "Trident Devices Panel" @{b}--------------------------------------------------------------------------- Trident Devices Panel ---------------------------------------------------------------------------@{ub} Here you can see the USB devices currently found in your system. Whenever you plug in a new device or remove it, it will (hopefully) appear here, unless something went wrong. The box will also show, which class driver is bound to the device, so you can tell, if your USB device is accepted by the stack or not. The 'Class Scan' gadget will manually again try to assign all the devices without a binding to a class. 'Release Binding' can be used to remove all bindings from a device (both device and interface bindings). This temporarily disables the function of the USB device. If there is a binding to a device and the class bound has a configuration GUI, clicking on the 'Settings' button will open the GUI for all interfaces or a device binding. If you only want to open the window of a specific interface, use the corresponding button inside the device information window (see below). Either by double-clicking on the device line or by clicking the 'Information' gadget, a detailed information window will be opened. In this window, all interfaces are shown. Again, there's the possibility to do a 'Class Scan', as well as removing interfaces bindings. By double clicking on an interface or by pressing the 'Settings' button, a configuration window of the class will be opened, if the class supports this. @{b}--------------------------------------------------------------------------- Forced Bindings ---------------------------------------------------------------------------@{ub} Starting with V1.32 of Poseidon and Trident V1.0, there is the possibility to force a device or an interface to bind to a certain class, even if it does not automatically do this. This might be useful for class drivers, that bind to vendor specific interfaces or for usb devices with broken interface descriptors. However, forcing a binding might not make work with the class (the class itself has to decide, if it is able to bind to the device or not) and you will get an error message, if this device is not supported nevertheless. To establish a forced binding, select the device entry (in the devices panel) or the interface entry (in the device details window). Then press and hold the right mouse button, as this will make a pop-up menu appear. Finally select the class you want to bind to. Note well that you might need to release the current binding first and then do a Class Scan to make the new binding active. Also, do not confuse device and interface bindings -- most class drivers will only bind to interfaces (see @{" Class Drivers " link classdrivers} for details). To remove a forced binding, just select "None" from the list of classes. Be careful with these forced bindings, they might render your USB stuff temporarily useless. Forced bindings are saved along the normal preferences. So you still don't see why to use Forced Bindings, eh? Here are a few examples: - Binding an USB scanner to the @{" rawwrap.class " link rawwrap.class} to use it with BetaScan. - Forcing bootmouse/bootkeyboard.class to a HID device and vice versa. - Assigning massstorage.class to a MSD device (Sony?) with wrong subclass/protocol. @endnode @node tridentclasses "Trident Classes Panel" @{b}--------------------------------------------------------------------------- Trident Classes Panel ---------------------------------------------------------------------------@{ub} This panel contains the list of the class drivers that have been added to the stack so far. By pressing the 'Dir Scan' button, all available class files from the SYS:Classes/USB directory will be added. However, you can manually add or remove classes using the 'Add' and 'Remove' buttons at the bottom of the panel. If a class has some user configurable settings, pressing the 'Configure' gadget will pop up its Prefs window. Normally, you will find the default class configuration here. Be sure not to remove the @{" hub.class " link hub.class}. This will take down any devices attached to downstream ports. A list of available classes can be found @{" here " link classdrivers}. @endnode @node tridentconfig "Trident Config Panel" @{b}--------------------------------------------------------------------------- Trident Config Panel ---------------------------------------------------------------------------@{ub} This panel contains configuration possibilities for the stack itself and all the available settings saved so far. Currently, the following things can be changed: SubTask Priority: This slider controls at which priority new subtasks, which were started by the stack, should run. The default is 5. However, you can increase this value to 20 or 21, so that e.g. the mouse movement is not interrupted by any other task. Boot Delay: Increase this time setting, if you plan to boot from mass storage devices. As the stack is started 100% asynchroneously during boot time, it cannot wait for USB devices to get ready before the Amiga starts booting from DOS. Especially an USB Zip drive needs some time to spin up. So if some USB device fails to boot from, try increasing this value. Otherwise, you can leave it this value at 0. Logging: With these four settings you can alter, which kind of messages may be generated at all. The last line shows the amount of memory used inside the internal Poseidon memory pool. Therefore, this number be a bit lower than the actual number of bytes allocated (but not too much). @endnode @node shelltools "Poseidon Shell Tools" @{b}--------------------------------------------------------------------------- Shell Tools and additional Software ---------------------------------------------------------------------------@{ub} There are several shell tools included in the Poseidon package for advanced users. - @{" AddUSBHardware " link addusbhardware} -> Adding hardware drivers - @{" AddUSBClasses " link addusbclasses} -> Doing a class scan - @{" PsdStackloader " link psdstackloader} -> Loading up the stack - @{" PsdDevLister " link psddevlister} -> Detailed USB system information - @{" PsdErrorLog " link psderrorlog} -> Printing out an error log - @{" PsdRestart " link psdrestart} -> Restart the stack - @{" PencamTool " link pencamtool} -> Versatile webcam utility - @{" pencam.vhi " link pencam.vhi} -> Pencam VHI Studio driver - @{" DRadioTool " link dradiotool} -> D-Link/GemTek USB radio tool - @{" UproarTool " link uproartool} -> MP3 player tool - @{" PsdRomTag " link romtags} -> Install/uninstall Poseidon residently @endnode @node addusbhardware "AddUSBHardware" @{b}--------------------------------------------------------------------------- AddUSBHardware ---------------------------------------------------------------------------@{ub} Command : AddUSBHardware 1.5 Template: DEVICE,UNIT/N,QUIET/S,REMOVE/S,ALL/S Examples: AddUSBHardware DEVS:USBHardware/highwayusb.device AddUSBHardware DEVS:USBHardware/highwayusb.device 1 REMOVE AddUSBHardware REMOVE ALL Purpose: Manually add or remove USB hardware to/from the Poseidon stack software After adding the hardware driver, a class scan is done automatically. Usage: DEVICE - required argument containing the (absolute) path and name of the USB hardware device driver to add or remove. UNIT/N - optional unit number, if multiple units are supported. Default is unit 0. QUIET/S - if QUIET is used, no messages are printed into the shell. REMOVE/S - try to remove the entry, if found, instead of adding it. Be careful to use the same path/filename you used to add the hardware. ALL/S - tries to add all units of the given device. If REMOVE is specified, it removes all entries, effectively taking the stack offline. @endnode @node addusbclasses "AddUSBClasses" @{b}--------------------------------------------------------------------------- AddUSBClasses ---------------------------------------------------------------------------@{ub} Command : AddUSBClasses 1.3 Template: QUIET/S,REMOVE/S Examples: AddUSBClasses QUIET AddUSBClasses REMOVE Purpose: Either scan SYS:Classes/USB directory and add all classes to the stack or remove all classes installed from the stack. Note that the classes will be flushed out of memory on the expunge of the main library, which might happen, if no hardware driver has opened the poseidon.library. So the right order would be to use AddUSBHardware first and then AddUSBClasses. Usage: QUIET/S - if QUIET is used, no messages are printed into the shell. REMOVE/S - remove all classes instead of adding them. @endnode @node psdstackloader "PsdStackloader" @{b}--------------------------------------------------------------------------- PsdStackloader ---------------------------------------------------------------------------@{ub} Command : PsdStackloader 2.1 Template: none Example: ENVARC:PsdStackloader PsdLoadModule ENVARC:PsdStackloader Purpose: This is the program (!) can contains the stack configuration within and is able to boot up the stack when called. It does @{" AddUSBHardware " link addusbhardware} and @{" AddUSBClasses " link addusbclasses} internally with the hardware drivers and classes given in the configuration. PsdStackloader is automatically created by @{" Trident " link usingtrident}. This program can and should be loaded as a @{" RomTag " link romtags}, if you want to startup the stack before booting. @endnode @node psddevlister "PsdDevLister" @{b}--------------------------------------------------------------------------- PsdDevLister ---------------------------------------------------------------------------@{ub} Command : PsdDevLister Template: none Example: PsdDevLister Purpose: Give a detailed list of all the USB devices currently in the system. It is appreciated that you include the output of this program for bug reporting. @endnode @node psderrorlog "PsdErrorLog" @{b}--------------------------------------------------------------------------- PsdErrorLog ---------------------------------------------------------------------------@{ub} Command : PsdErrorLog Template: none Example: PsdErrorLog Purpose: Prints out all information, warning and error messages accumulated so far in the Poseidon stack. These messages will automatically be flushed, so calling PsdErrorLog another time will only reveal the new messages since the last call. @endnode @node psdrestart "PsdRestart" @{b}--------------------------------------------------------------------------- PsdRestart ---------------------------------------------------------------------------@{ub} Command : PsdRestart Template: none Example: PsdRestart Purpose: Mainly to be used as a RomTag. Restarts the stack by releasing all bindings and doing a class scan afterwards. The main purpose is to restart the subtasks that were created during boot time as dos.library aware processes. This is neccessary for mass storage devices to be able to automount partitions after bootup. PsdRestart can also be used to rebind mice and keyboards that were bound to the bootmouse/bootkeyboard.class during startup, but now should be switch to the hid.class instead. PsdRestart is part of the @{" PsdRomTag " link romtags} procedure. @endnode @node pencamtool "PencamTool" @{b}--------------------------------------------------------------------------- PencamTool ---------------------------------------------------------------------------@{ub} Command : PencamTool 1.6 Template: TO/A,PICNUM/N,INTERVAL/N,UPTO/N/K,NOBEEP/S,GAMMA/K,SHARPEN/S, TEXT/K,FONT/K,FONTSIZE/N/K,UNIT/N/K Examples: PencamTool Snap.ppm PencamTool Snap.ppm 0 GAMMA 0.45 SHARPEN PencamTool Movie%04ld.ppm INTERVAL 0 GAMMA 0.5 PencamTool Webcam.ppm GAMMA 0.45 SHARPEN TEXT "Platon's Cam" FONT small.font FONTSIZE 6 NOBEEP PencamTool Shotseries%03ld.ppm 0 UPTO 79 GAMMA 0.45 SHARPEN Purpose: Command line tool to read out images from an USB webcam using the STV680 chip (Vendor ID = 0x0553, Product ID = 0x0202). This includes the Aiptek Pencam series as well as a few more cheap cameras out there. Images are saved as true colour graphics in the Portable Anymap format (PPM), see NetPBM package on Aminet for a lot of conversion tools. Moreover, gamma correction and white balance may be applied to the picture as well as a sharpening filter. Optionally, text may be pasted directly into the picture using a user definable font. Usage: TO/A - mandatory filename to save the picture to. This filename may also contain a format string such as "%ld" (do not forget the 'l') to generate a number when using the INTERVAL option. PICNUM/N - number of the picture to load from the camera's RAM, starting with 0 for the first picture. If no picture exist with this number, you will get garbage. Omitting this parameter will take a current snapshot. INTERVAL/N - if this numeric parameter is given, PencamTool will loop and take pictures at the given interval (in ticks, 50 ticks is one second). Interval is only sensible, if you don't use the PICNUM argument. Use Ctrl-C to abort the PencamTool. UPTO/N/K - if specified, multiple pictures can be grabbed in one go, starting at the PICNUM number and stopping at the UPTO number. Be sure to give a format string such as "%ld" inside the filename or you will write all pictures to the same image. If no PICNUM is given, but INTERVAL instead, UPTO describes the image number to stop the regular picture taking. NOBEEP/S - disable BEEP on downloading an image. GAMMA/K - enable white balance and gamma correction with the given floating point gamma value. 0.45 is a good setting. If you only want white balance and no gamma correction, use a value of 1.0. SHARPEN/S - apply a highly optimized 5x5 sharpen filter on the image. TEXT/K - optionally adds the given line of text to the bottom of the picture. If the line is too long to fit, it will be truncated. FONT/K - name of the font to use (e.g. xen.font). If this parameter is missing, the default system font will be used. FONTSIZE/N/K - size of the font in pixels UNIT/N/K - if several cameras are connected, specify the unit to use. Defaults to unit 0. @endnode @node pencam.vhi "Pencam VHI Studio Driver" @{b}--------------------------------------------------------------------------- Pencam VHI Studio Driver ---------------------------------------------------------------------------@{ub} File : Libs:VHI/pencam.vhi Version: 1.2 (beta) Purpose: This is a VHI Studio driver for the Pencam series. It allows to take snapshots or download the images from USB webcams using the STV680 chip (Vendor ID = 0x0553, Product ID = 0x0202). This includes the Aiptek Pencam series as well as a few more cheap cameras out there. Usage: The driver will grab the first free webcam on opening VHI Studio. Therefore, Poseidon must be running before starting VHI Studio. In VHI Studio you both have the possibility to take snapshots and to download the pictures already stored in the memory of the camera. You can create some animations at about 2-3 fps. The video streaming format of the STV680 chip is not documented, so high rate video will probably not be possible. @endnode @node dradiotool "DRadioTool" @{b}--------------------------------------------------------------------------- DRadioTool ---------------------------------------------------------------------------@{ub} Command : DRadioTool 1.1 Template: ON/S,OFF/S,FREQ/K/N,SCAN/S,AUTO/S,SIGNAL/S,UNIT/N/K Examples: DRadioTool ON SCAN AUTO DRadioTool FREQ 104000 Purpose: Very simple shell tool to control an USB Radio manufactured by D-Link or GemTek. Only radios with Vendor ID = 0x04b4 and Product ID = 0x1002 are supported. Usage: ON/S - turns the radio on. OFF/S - turns the radio off again. FREQ/K/N - sets the current frequency to the given value. It must be given in KHz and range between 87 MHz and 108 MHz. SCAN/S - starts a frequency scan. It starts at 87 MHz, if no FREQ value had been given and stops at 107 MHz. If a radio channel is detected it will output its frequency in KHz on the shell. The last found channel will be kept. The scan can be aborted at any time using Ctrl-C. AUTO/S - only useful in conjunction with the SCAN switch. If a station is found, the program will pause for three seconds, asking the user to press Ctrl-C to keep the radio station found. SIGNAL/S - sets the shell return value to WARN (5), if no radio station is detected on the current frequency. If there's a stereo signal, it will return OK (0). This switch can be used to implement a manual scan routine. UNIT/N/K - if multiple radios are connected, you can choose the right unit with this argument. Defaults to unit 0 of course. @endnode @node uproartool "UproarTool" @{b}--------------------------------------------------------------------------- UproarTool ---------------------------------------------------------------------------@{ub} Command : UproarTool 1.0 Template: DEVINFO/S,FILELIST=FL/S,UPLOAD=UL/K,DOWNLOAD=DL/K,DELETE=DEL/K, FORMAT/S,EXT/S,AS/K Examples: UproarTool DEVINFO UproarTool FL UproarTool UL AimeeMann-NightmareGirl.mp3 AS NghtMare.mp3 UproarTool DL 1 EXT UproarTool FORMAT UproarTool DELETE HormonBn.mp3 Purpose: This is a tool for managing MP3 players that use a common Samsung MP3 chipset. The protocol is not publically available, but similar to the one found for the "Samsung Uproar SPH-M100". I believe, it should work with lots of different player implementations. It works here with the "Valencia MPX Player", I bought in Dec'02 (for EUR 99). The UproarTool will bind to any device with VendorID = 0x04e8, as the product IDs generally differ. If you've got an MP3 player, that is not a mass storage class device and the VendorID matches, you could give this program a try. At least try the DEVINFO keyword and send the output to me. The source code is available to those, who want to modify it to work with their player. The shell tool allows everything the Windows software is able to do. However, the MP3 player is rather sensible to getting out of sync. If that happens, either replug the device or try the command multiple times, until it works. My MP3 Player has 64 MB of internal memory and a MMC/SD slot. To operate on the external memory available from the MMC/SD slot, use the EXT switch on all operations. Usage: DEVINFO/S - Returns the device ID. For my Valenica MP3 Player, it's: "Device ID String: '2.1.0.10 20000329CPAD00 '" FILELIST=FL/S - Lists the files found in the internal memory (or external when using the EXT switch). If you only get garbage, try to format the media. UPLOAD=UL/K - Uploads the given file to the MP3 player (either into internal memory or external memory, if EXT is given). If the file name is longer than 8+3 characters, it will be mutilated to fit. When specifying the AS keyword, that name will be used instead. DOWNLOAD=DL/K - Downloads the give file from the MP3 player. The file can either be specified by its track number as shown in the filelist or by its exact name (case sensitive). The downloaded file will be stored under its name in the current directory or stored at the location and name specified by the AS keyword. To download a file from external memory, use the EXT switch. DELETE=DEL/K - Deletes a file from the MP3 player. As with download, the file can be given either as the track number or its exact name. To delete a file from external memory, use the EXT switch. FORMAT/S - If given, erases the whole internal or external memory, depending on the use of the EXT switch. EXT/S - Specifies whether the command should operate on the internal memory or on the memory card supplied by the MMC/SD slot. AS/K - alternate filename to use for downloading or uploading. Bugs: - There isn't much error handling. - Gets easily out of sync. - Doesn't generate a valid date when uploading files. - Several fields of the protocol data are unknown. @endnode @node classdrivers "Included class drivers" @{b}--------------------------------------------------------------------------- Class Drivers ---------------------------------------------------------------------------@{ub} The initial Poseidon package includes the following class drivers: - @{" hub.class " link hub.class} for the root hub and any external hubs - @{" hid.class " link hid.class} for all kinds of input devices - @{" bootmouse.class " link bootmouse.class} for mice and tablets supporting the "boot protocol" - @{" bootkeyboard.class " link bootkeyboard.class} for keyboards supporting the "boot protocol" - @{" printer.class " link printer.class} for usb printers - @{" massstorage.class " link massstorage.class} for standard storage devices (CF-readers, ZIP etc.) - @{" cdcacm.class " link cdcacm.class} for USB modems confirming to the ACM standard - @{" rawwrap.class " link rawwrap.class} to access vendor specific interfaces via usbraw.device - @{" serialpl2303.class " link serialpl2303.class} for Prolific USB->serial adapters Please understand that only devices can be supported that stick to the standards determined by the USB specifications. Unfortunately, there are many vendors that implement their own undocumented protocols. These devices should be avoided as support by Poseidon is at least doubtful and driver development is difficult, if no protocol information is available. Scanner and DigiCam drivers will have to be provided by third parties, as those normally fall into the case mentioned above. Class drivers are normally stored in SYS:Classes/USB. Do not place any other files into this directory or you will obviously crash Poseidon. There are two types of class drivers: Device bound or interface bound. As there may be multiple interfaces in one USB device (like a cordless desktop with mouse and keyboard), multiple classes may bind to the one USB device. The class be added to or removed from the system either using @{" Trident " link usingtrident} or the @{" AddUSBClasses " link addusbclasses} shell command. @endnode @node hub.class "The Hub Class Driver" @{b}--------------------------------------------------------------------------- hub.class ---------------------------------------------------------------------------@{ub} Class: hub.class 1.22 Binding to: device, classcode 9 (HUB) Config GUI: none This is the root of all evil. The hub.class controls the root hub and all external hubs in the device chain. Whenever a device is plugged into the downstream ports, this class enumerates and configurates it, automatically trying to add its features to the system. If its disconnected, it magically handles the removal. External hubs can be added to the chain to provide more downstream ports (or just to have the possibility to connect the devices at a different place). Hubs normally can be self-powered or bus-powered. Please avoid the self-powered ones, if you want to connect power-hungry devices such as drives to the chain, otherwise the device may malfunction or even stop the hub from working, possibly taking all the other devices with him. If the current drainage is too much to handle, the hub should disable that port automatically. That's the theory. It normally behaves differently :-( Some keyboards and monitors also have embedded hubs. Normally a nice thing, but remember the power problems mentioned above. The hub.class can be installed as a @{" RomTag " link romtags}. @endnode @node hid.class "The HID Class Driver" @{b}--------------------------------------------------------------------------- hid.class ---------------------------------------------------------------------------@{ub} Class: hid.class 1.6 Binding to: interface, classcode 3 (HID), any subclass, any protocol Config GUI: seperately for each interface and default class settings. After months of hard work and over 450 KB of source code, I can present you the second really updated version of the hid.class. This is a generic and very versatile class driver for human interface devices (HID). This can be anything from tablets, joysticks, magic carpets, baseball bats, telephones, monitors, barcode scanners, power supplies to less common things like mice, keyboards and joysticks/joypads. Ah yes. Wheels are supported :) You may connect or disconnect the device at any time. The hid.class has got a very large and complicated GUI. There's much you can do wrong, but don't be afraid of it, we will get through it step by step. You might also want to have a look at the great HID class tutorial found in the Total Amiga Issue 14. It is available online at: http://www.totalamiga.org/pdf/totalamiga_14.pdf Be sure to have installed the new @{" input.device " link input.device} to have a 100% compatible mouse and keyboard replacement. The hid.class can be installed as a @{" RomTag " link romtags}, but is only available after booting. @{b}--------------------------------------------------------------------------- Global Settings ---------------------------------------------------------------------------@{ub} The hid.class driver has both global default settings for all and for individual devices. The global default settings can be opened by double clicking the hid.class entry, whereas the individual prefs will show up using the 'Settings' button in the device list or in the detailed device information window. Global Settings include: Shell console window: Whenever a program is started, this console window will be used to print the output to. If you don't want any output, use NIL: Shell default stack: Stack to use when launching external programs. Do not set this value too low or the program might crash. Enable keyboard reset: If active, generating a Ctrl-left Amiga-right Amiga key combination will reboot the machine. Hijack reset handlers: If there are any keyboard reset handlers in the system, enabling this option will call them before rebooting. Reset delay: Delay to wait before rebooting the machine, if (and only if) reset handlers are found in the system. LowLevel Library joypad emulation: This version of the hid.class patches the lowlevel.library ReadJoyPort() function to allow multitasking friendly programs that make use of this library to react upon USB joypads (or actually any USB input device). The low level library supports up to four ports. Port 0 is usually used by the mouse, port 1 is the standard port for joysticks/joypads. The HID class has four options how to handle the input data: - Don't touch: The movement and button data for is not modified by the hid class. This is the default for the ports 0, 2, and 3. - Overwrite with USB: This will kill the original data that might had come from the internal ports and overwrites it with the joypad data for this USB interface. Note well: If you have multiple joypads connected, take care which setting you have selected for each port, because only the last interface with this option will actually send the joypad data to the game. - Merge with USB: This option merges the input data of the lowlevel.library with the USB stream. This only works, if the connected device on the original Amiga ports is NOT a mouse (because then the streams are incompatible). Merging should be the preferred method, because it leaves the original joysticks working. - Disable: Turns off the port for the application. Keyboard Settings include: - Two listviews where you can select which key of an USB keyboard should be mapped to a raw key on the Amiga keyboard side. This cannot replace selecting a PC keymap in the system input prefs, as some shift-key combinations just are handled differently on PC keyboards. - Restore default keymap: Pressing this button will restore the default keymap that should work well for most users. - Track incoming key events: Enabling this switch will make the USB Keymap selection jump to the last key on the USB keyboard you've pressed. This makes it easier to find the corresponding keys in the list. @{b}--------------------------------------------------------------------------- Reports, Collections, Items, Actions ---------------------------------------------------------------------------@{ub} The thing that makes the HID stuff so complicated it the format of the data. The USB implementers forum tried to make it as versatile as possible to suit very input device you could think of. Therefore, data is sent in so called Reports. These Reports may contain several Collections. Each collection can contain one or multiple Items (so Items are joined into Collections of logical or physical order). Items again, can be either variables or arrays, the latter having lots of so called Usages. In short, an Usage shows, what a specific Item does represent. In Poseidon each Usage can be assigned multiple Actions. The hid.class knows some (>1500) of these Usages on its own and defines sensible standard actions for some of them, so you can use your keyboard or your mouse with it automatically. Now where does this lead us to? Hm. Well, let's start with Items. Each Item has a well defined range of values it can contain. An item can have different features: Linear vs. Non-Linear, Absolute vs. Relative, Variable vs. Array, just to mention a few. There are three different types of items: - Input items: These are the standard items you will encounter for HID devices in most cases. They report data from the device to the computer. - Output items: Output items are used to transmit data from the computer to the "input" device, such as LED states on a keyboard or the force feedback data for joypads. - Feature items: Like output items, but rarely used. They normally are used to set internal features. There is one important difference between variables and arrays. Variables only have one Usage which will be assigned specific value inside a range. Arrays, however, are associated with lots of different Usages, which just appear to be in the array, or, well, don't (so the values of Usages in array Items can only either be 0 (non-existant) or 1 (existant)). For array Items normally define lots of Usages with the same or similar behaviour, these Items have an extra default entry. This one acts as a default for all usages defined, if (and only if) no other behaviour is defined for the particular Usage. This will be explained again a bit later. @{b}--------------------------------------------------------------------------- Triggers ---------------------------------------------------------------------------@{ub} You can define as many Actions for a single Item as you want -- each Action can be set to be triggered in one of four different ways: Trigger definitions: - Down: Whenever the value increases, i.e. when a button or key is pressed down, the Action is triggered. - Up: If the value decreases, i.e. when a button or key is released the Action is triggered. - Any: This is a combination of Up and Down triggers, i.e. whenever the value changes, the Action will be executed. - Always: No matter what the value is, whenever a new data package with a new valid data value is received, the action is launched. - NaN : "Not a Number", meaning that new information was not present in the report back from the device. This is only rarely useful for items that report a release of a switch by returning an out of range value (like hatswitches). Now this means you can assign different actions to a key being pressed and to a key being released. You can also distinguish between so-called one-shot events and continuous events (like mouse movement). @{b}--------------------------------------------------------------------------- Action Types ---------------------------------------------------------------------------@{ub} Let's get to the core of the thing, the Action types and their definitions: - @{b}No action@{ub} Does nothing. If you want to temporarily deactivate an action, just change the type to this one. - @{b}Qualifiers@{ub} The qualifiers contain the state of the shift, caps lock, ctrl, amiga etc. keys. With this Action you have the possibility to change one of these qualifers to a new value (according to the mode). These are the available modes: - Set: Enable the qualifier, no matter what the received value is. - Clear: Clear the qualifier, no matter what the received value is. - Toggle: If the qualifer was set, clear it and vice versa. - Assign: If the value was 0, clear the qualifier, else set it. Normally, you only want to use this for keyboards. Luckily, the default Actions already define the correct key assignments. Example: Two different Caps Lock-Key definitions: - Default definition (Caps lock toggles by pressing the caps lock key) - On the 'Caps Lock' keyboard item: Action: Keymapping, Trigger: Any Action: Qualifiers, Trigger: Down, "Toggle Caps Lock" - On the 'Shift' keyboard items (two of them): Action: Keymapping, Trigger: Any Action: Qualifiers, Trigger: Down, "Assign Left/Right Shift" - Alternate definition (Pressing caps lock enables it, until the shift key is pressed) - On the 'Caps Lock' keyboard item: Action: Keymapping, Trigger: Any Action: Qualifiers, Trigger: Down, "Set Caps Lock" - On the 'Shift' keyboard items (two of them) Action: Keymapping, Trigger: Any Action: Qualifiers, Trigger: Down, "Clear Caps Lock" Action: Qualifiers, Trigger: Down, "Assign Left/Right Shift" More hints: - You can also use this to enable the shift key on the middle mouse button. - By adding three actions for the qualifiers Ctrl-Left Amiga-Right Amiga you can create a keyboard reset (by hand). - @{b}Keymapping@{ub} Just maps the USB keyboard keys to the Amiga keyboard. It will generate both down and up events for a key. The keyboard mapping can be changed in the keyboard panel. Note that keymapping will really only work with keys. Don't try to assign this to other Items. - @{b}Raw key@{ub} Sends a single key down or key up stroke event. Just choose the key you want to send and select, if it should be key press or release. Please notice that you should take care of what you're doing. Don't forget to send the corresponding key up events, or you might end up getting a lot of repeated keys (until you press that key again). Anyway, if that's too complicated for you, you can still use the Keystring or Vanilla Key Action. - @{b}Vanilla key@{ub} (detached) It's tasty and smells good. But generates one specific custom key according to the description given in the string gadget. The description must follow the normal rules for commodity keys. Here's a short list of whats possible (roughly taken from the RKM Libraries): ------------------------------------------------------------------------- The following regular expression outlines the format of the input event description string: [class] {(qualifier|synonym)} [highmap|ANSICode] Class can be any one of the class strings in the table below. If the class is not explicitl stated, it will assume it is rawkey. Class String Input Event Class ------------ ----------------- "rawkey" IECLASS_RAWKEY "newprefs" IECLASS_NEWPREFS "diskremoved" IECLASS_DISKREMOVED "diskinserted" IECLASS_DISKINSERTED Qualifier is one of the qualifier strings from the table below. Notice that there can be more than one qualifier (or none at all) in the input description string. Qualifier String Input Event Class ---------------- ----------------- "lshift" IEQUALIFIER_LSHIFT "rshift" IEQUALIFIER_RSHIFT "capslock" IEQUALIFIER_CAPSLOCK "control" IEQUALIFIER_CONTROL "lalt" IEQUALIFIER_LALT "ralt" IEQUALIFIER_RALT "lcommand" IEQUALIFIER_LCOMMAND "rcommand" IEQUALIFIER_RCOMMAND "numericpad" IEQUALIFIER_NUMERICPAD "repeat" IEQUALIFIER_REPEAT "midbutton" IEQUALIFIER_MIDBUTTON "rbutton" IEQUALIFIER_RBUTTON "leftbutton" IEQUALIFIER_LEFTBUTTON "relativemouse" IEQUALIFIER_RELATIVEMOUSE Synonym is one of the synonym strings from the table below. These strings act as synonyms for groups of qualifiers. Notice that there can be more than one synonym (or none at all) in the input description string. Synonym Synonym String Identifier ------- ---------- "shift" IXSYM_SHIFT /* look for either shift key */ "caps" IXSYM_CAPS /* look for either shift key or capslock */ "alt" IXSYM_ALT /* look for either alt key */ Highmap is one of the following strings: "space", "backspace", "tab", "enter", "return", "esc", "del", "up", "down", "right", "left", "f1", "f2", "f3", "f4", "f5", "f6", "f7", "f8", "f9", "f10", "help". ANSICode is a single character (for example `a') that Commodities Exchange looks up in the system default keymap. Here are some example description strings. For function key F2 with the left Shift and either Alt key pressed, the input description string would be: "rawkey lshift alt f2" = "lshift alt f2" ------------------------------------------------------------------------- More useful strings might be: "ramiga x" : cut marked operation in most applications. "ramiga c" : copy operation. "ramiga v" : paste operation. - @{b}Key string@{ub} (detached) The ansi string contained in the corresponding gadget is emulated using keyboard presses. Whatever program is currently in input focus will receive the given key presses. You can also use the following special characters: - "\\n": CR (Return key) - "\\r": CR (Return key) - "\\t": TAB - "\\\\": normal backslash Moreover you can also generate other special keys enclosed in angle brackets (e.g. "", see the Vanilla key Action for details). This is actually some kind of keyboard macro. - @{b}Mouse position@{ub} Changes the position of the pointer. Either uses relative or absolute coordinates for each axis. For the latter, Tablet events are generated (which unfortunately are not interpreted correctly by a few programs like Cinema4D). Note that the trigger for this should normally be 'Always'. - @{b}Buttons@{ub} Changes the state of the left, right and middle mouse button (forth mouse button is also available through NewMouse, fifth is only generated for Tablet Events). Just like with the Qualifiers Action, there are different modes: - Press: Press the specified button, no matter what the value might be. - Release: Release the button, independently of the value. - Flip: Press the button, if was previously not set and vice versa. - Assign: Set the state of the button according to the item's value. - @{b}Tablet data@{ub} This one is used to fill some additional tablet data in for the system -- if the tablet provides it. It always assigns the value of the Item to one of the following entries: pressure, rotation around the three axis, proximity (if the stylus is currently in range) and Z position (how high above the tablet the stylus is levering). Note that a few stupid tablets only send this information after being initialized into a special mode. Wacom tablets are much worse, they only provide this kind of data in a vendor specific Report, which does not comply to the HID specification. Too bad. - @{b}Digital joystick@{ub} Allows the use of analogue or digital joysticks and sending their data to applications using the lowlevel.library. The lowlevel.library supports four direction bits and seven buttons for four different ports. Just like with the several Actions, there are different modes: - Push: Push the button or direction, independently of the value. - Release: Release the button or direction, independently of the value. - Toggle: Toggle the old value. - Assign: Set the state of the button or direction according to the item's value. As most digital joypads do not report each direction in seperate items, there is a special "hatswitch" direction. It takes a value from 0 to 7 corresponding to the eight possible directions and sets the up/down and left/right bits according to the value. Unfortunately, there is no value for the central position when the pad is not in use (stupid, really). Therefore, by default an action with NaN trigger with "Release Hatswitch" is generated for digital hatswitches. However, this action interferes with the analogue joypad option, so you might want to remove it, if you want to use the analogue sticks for the very same port. - @{b}Analogue joystick@{ub} Not yet implemented. The reason is simply that there is no interface on the operating system side that would currently support analogue joysticks in a sensible way (and a way supported by games). Therefore, a new interface for such input data in needed first. - @{b}Scrollwheel@{ub} Now this is for all those people you kept on nagging. Allows the definition of a scroll wheel, either vertical or horizontal conforming to the NewWheel standard. Under AmigaOS you will need MUIWheelPatch to allow MUI programs use the wheel events sent automatically, in MorphOS this is already incorporated. If the wheel information is not present as delta data with a negative min and positive max range, you can also use the four direction options instead. When using those, the distance slider determines the amount of events generated. The single direction mode can also be used for assigning a page up or page down keyboard functionality. And don't forget to add a nice sound to the Wheel whenever you use it to impress your Wintel user neighbours and friends :) - @{b}Sound@{ub} (detached) Allows you to play back a soundfile whenever this Action is triggered. All formats supported by your installed sound datatypes can be used. The volume can be chosen between 0 and 64. This is a good idea to use for launching tasks or when using a key to reboot the machine. Or just for the next DJ session :) Again, note well that you can have different sounds for down and up events. - @{b}Shell@{ub} (detached) This is one of the most powerful Actions. It allows the execution of any shell command (or script). You can choose, if the class should wait for the command to terminte before executing the next Action or if should run each command asynchroneously. For input/output handling, the console file handle is used as specified in the Global Settings menu, as well as the stack settings. Yeah, this really rules. Using the Rx command, you can also send small Arexx commands. Examples: - On the 'E-Mail key': YAM:YAM - On the 'Scan Previous Track' key: rx "ADDRESS Amplifier.1; playprev" - @{b}Arexx@{ub} Sorry, not yet implemented. - @{b}HID output@{ub} This allows you to send data from the computer to the device, if supported. Normally, output items are present for the LEDs of a keyboard or force feedback joypads. However, the use is not limited to this: changing the heating temperature for an USB coffee cup could be changed here aswell. Just select the item from the listview and the operation accordingly. The last (or current) state of the items is shown in this listview aswell. - @{b}HID feature@{ub} Same as above, but for feature items. - @{b}Miscellaneous@{ub} This contains a few, but very handy events: - Activate window: Activates the window, at the current mouse position. Put this Action into one of the mouse position Items with Trigger=Always and you will get a SunMouse/AutoPoint feature for free. Also, try to put this into the right mouse button Item at the top of the action list to and you will get a feature very similar to the RightSunMouse tool (i.e. you will always get the menu of the window you're currently under). - Window to front: Puts the current window to front. Put this Action into the left mouse button Item and you will get a ClickToFront commodity for free. - Window to back: Sends the current window to back. - Close window: Send a close window event. Comes quite handy. - Zip window: Has the same effect as pressing the Zip/Zoom gadget in the upper right corner of a window. - Screencycle: Just exactly that. Brings the next screen to the front. - WB to front: Makes the Workbench the frontmost screen. - Display beep: Calls the DisplayBeep() function of intuition. Doh! - Reboot machine: Warning, will reboot the machine, if this Action is triggered. There is no way back! - @{b}Variables@{ub} The new version of the hid.class allows the use of internal variables. With this Action you can do simple calculations on the eight global and local variables. Global means that the values are carried across each interface and is global accessible to all USB HID devices. Local means that each interface as its own set of the eight local variables. The contents of a variable is modified according to these operations: - "assign :=" (assign) Assigns the input value to the variable. - "not := !" (assign inverted) Sets the value to 1, if the input value was zero, otherwise sets it to zero. - "add +=" (add) Increases the current variable by the given value. - "sub -=" (subtract) Decreases the variable by the input value. - "mult *=" (multiply) Multiplies the variable by the input value. No overflow checks are done, so take care. - "div /=" (divide) Divides the variable by the input value. If the input value is zero, the operation is ignored. - "mod %=" (modulo) Does a modulo operation on the variable (remainder of the division). If the input value is zero, the operation is ignored. - "and (x && y)" (logical and) Assigns 1 to the variable, if the variable was non zero before and the input value is not zero. - "nand !(x && y)" (logical not and) Assigns 1 to the variable, if the variable was zero before or the input value is zero. If both were non-zero, the variable is set 0. - "or (x || y)" (logical or) Sets the variable to 1, if the variable or the input value were not zero. - "xor (x ^^ y)" (logical xor) Toggles the variable, if the input value is not zero. - "and not (x && !y)" (logical and not) Assigns 1 to the variable, if the variable was non zero before and the input value is zero. - "bw and (x & y)" (bitwise and) Clears the bits of x that are not set in y. - "bw nand ~(x & y)" (bitwise not and) Takes the old value of x and performs a bitwise and operation, then before writing back the value, it is bitwise inverted. - "bw or (x | y)" (bitwise or) Merges the bitmask of y to x. - "bw xor (x ^ y)" (bitwise exclusive or) Flips the bits of x that are set in y. - "bw and not (x & ~y)" (bitwise and not) Clears the bits in x that are set in y. - "shift <- (x << y)" (arithmetic shift left) Shifts the value of the variable by the amount of bits to the left that's given in the input value. This is equivalent to a multiply operation by 2^y. - "shift -> (x >> y)" (arithmetic shift right) Takes the contents of the variable and shifts it to the right by the amount of bits specified in the input value. The sign of the variable is maintained. The input value is normally the item value, possibly modified by Abs->Rel, Clipping or Scaling operations (see below), but can also be taken from a different source using the input value redirection switch. @{b}--------------------------------------------------------------------------- Advanced options ---------------------------------------------------------------------------@{ub} The new hid.class version introduces a new set of possibilities. This allows to effectively write small "programs" for Actions. We will explain the options and give examples for its use. - Abs->Rel (Delta transformation): Say you have items with absolute values. But for your operations, you will need the changes between the old value and the new one. So this switch enables the conversion from an absolute item to a relative one. It will only work with variable items and not with arrays. This can be used e.g. for tablets returning absolute coordinates and you want to use relative - Clip (Item value clipping): Enabling this option will give you two sliders and a checkmark option. With clipping enabled you can set the minimum and maximum range (in percent) of the incoming value. By using a minimum value thats higher than the maximum value, the resulting value will be inverted (e.g. using a maximum of 0 and a minimum of 100 will effectively flip the value within the range). Selecting the stretch option automatically scales the clipped value back to the original range. This comes very handy e.g. for tablets when you want to shrink the usable area a bit because the outer borders are usually pretty hard to reach. - Scale (Item value scaling): You can change the range of values returned by scaling it to a new selected interval, when using this switch. Using smaller maximum values than minimum values will effectively flip the range. Say you have an analogue joypad and it returns values between 0 and 255 for its axes (128 being the center position). By using a new minimum of -16 and a maximum of 16, you have moved the center 0 and moreover scaled the the joypad values to be suitable for relative mouse movement. - CC (Pre-condition code): This is a very powerful switch. It allows to define a condition which must be valid for the Action to take place. If the given condition is not met, the Action is ignored. The condition code works like a simple equation with two operands (called Var1 and Var2) and a testing operation (CC). The operands Var1 and Var2 can be one of these: - Eval. item value: This is the item value after it has been processed through the optional Abs->Rel, Clipping and Scaling operations. - Orig. item value: The original item value, untouched by the operations mentioned above. - Constant: The given constant value entered in the left or right constant fields below. - Click count: Represents the number of clicks done within the double click time span. A 'click' is defined as a 'up to down' transition for an item. E.g. pressing a button twice (within the time span defined with the system input prefs program) will result in a click count value of 2. Of course, the click count will not stop at 2, if you click more often. This allows the detection of triple clicks etc.. For example, I'm using five clicks for causing a window-to-front-event. If the time of the last click exceed the double click time span, it will be set back to 0. Click count only returns valid results for variable items, not for arrays. - Click time: Returns the time in milliseconds a button is being pressed and held. Note, that this is only reasonable to use with 'Up' or 'Always' triggers. - Qualifiers: This value holds the current state of the USB key qualifiers. It is usually used in conjunction with the "bw and" operation to check for a special combination of qualifier keys being pressed. The qualifiers are the sum of the following values added together for the keys being pressed: Qualifier String Input Event Class Value ---------------- ----------------- ----- "lshift" IEQUALIFIER_LSHIFT 1 "rshift" IEQUALIFIER_RSHIFT 2 "capslock" IEQUALIFIER_CAPSLOCK 4 "control" IEQUALIFIER_CONTROL 8 "lalt" IEQUALIFIER_LALT 16 "ralt" IEQUALIFIER_RALT 32 "lcommand" IEQUALIFIER_LCOMMAND 64 "rcommand" IEQUALIFIER_RCOMMAND 128 "numericpad" IEQUALIFIER_NUMERICPAD 256 "repeat" IEQUALIFIER_REPEAT 512 "midbutton" IEQUALIFIER_MIDBUTTON 4096 "rbutton" IEQUALIFIER_RBUTTON 8192 "leftbutton" IEQUALIFIER_LEFTBUTTON 16384 - Random bit: Returns 0 or 1 on a random basis. For example, this can be used to generate autofire. - Random value: Returns a random in the whole integer range (-2^31 to (2^31)-1). - Timer: Returns the system time in milliseconds. - Local var 1-8: Represents the current value of the selected local variable for the interface. These variables can be used for temporary calculations or modes. - Global var A-H: Contains the current value of the selected global variable. These variables are carried across interfaces and can be used to transmit information from one interface to another (ever wanted to control the force feedback of a joypad with an USB keyboard?). Here's the list of operations (condition codes): - "==" (equal) Only performs the Action, if Var1 and Var2 are the same. - "!=" (not equal) Only passes the test, if Var1 and Var2 are different. - "<" (less than) If Var1 is really smaller than Var2, the Action is processed. - "<=" (less or equal) Performs the Action, if Var1 is smaller than or equal to Var2. - ">" (greater than) Only is a valid condition, if Var1 is really greater than Var2. - ">=" (greater or equal) Like above, but also passes if Var1 and Var2 are the same. - "and" (logical and) If both Var1 and Var2 are not zero, this condition is met. - "nand" (logical not and) The expression is valid if not both Var1 and Var2 are non-zero. - "or" (logical or) Passes the test, if Var1 or Var2 (or both) are not zero. - "xor" (logical exclusive or) Performs the Action, if either Var1 or Var2 are not zero (but not both). - "and not" (logical and not) The condition is met if Var1 is not zero, but Var2 is zero. - "bw and" (bitwise arithmetical and) Performs a bitwise 'and' operation on Var1 and Var2. If at least one bit of Var2 is also set in Var1, the test is passed successfully. - "bw or" (bitwise arithmetical or) Does a bitwise 'or' operation on Var1 and Var2. If at least one bit is set in Var1 or Var2 (i.e. not zero), the test is passed. Actually, this is the sames as the normal "or" operator. - "bw xor" (bitwise arithmetical exclusive or) Does a bitwise 'exclusive or' operation. The bits of Var1 are inverted at the positions where Var2 has a bit set. If the resulting bitmask is not zero, the Action is performed. - "bw nand" (bitwise arithmetical inverted and) Just like "bw and", but returns the inverted result. So the condition code "bw and" and "bw and not" has a similar relationship as between "==" and "!=", but uses bitmask attributes instead. - "bw and not" (bitwise arithmetical and with inverted operand) Just like "bw and", but inverts the bitmask given in Var2 first. The condition codes are very powerful and allow about every combination of events to limit an Action to. If you need two different conditions to be present, you can use temporary variables to store the immediate result of each component and then test the final result in the actual Action. - Val (Input value redirection): This allows the value that is used for the specified action not only to be taken from the item itself, but from the very same sources, we mentioned as the operands for condition codes. Together with the Variables Action type, this allows all kinds of calculations. I actually wanted to do some more explainations and examples, but I just don't have the time to. And most of the people won't read the manual anyway. @{b}--------------------------------------------------------------------------- Configuring the Beast ---------------------------------------------------------------------------@{ub} I hope the whole description was intelligible so far. Now, how do we generate or modify new Actions? Just select one of the Item in the upper right list view of the Collection you've chosen before in the upper left list view. This will list up all the Actions defined for that Item in the lower left list. If this list is empty, no Action was defined and triggering the Item will not do anything. To generate a new Action, click on the 'New'-Gadget. It will create a fresh and clean Action, which defaults to 'No action'. Now click on the cycle gadget to choose which kind of Action you want to have for the selected Item. Choose its options accordingly. To delete an Action, select it from the list and press the 'Del' button. You can also duplicate an action by pressing the 'Copy' button. Actions are normally processed in the order they appear in the list. Therefore, using the 'Up' and 'Down' gadgets, you can rearrange the Actions to your needs. However, note that some Actions will be executed detached from the normal flow in a seperate task. These activities are shown above with the 'detached' keyword and are those, which potentially take more time to fulfill. This is done to avoid the input device (mouse, keyboard, etc.) being locked during the execution. Again, the short note for array Items: There is a default action list for these items. It will only be used if the specific subitem has an empty Action list (i.e. @{b}no@{ub} action defined). Warning: All Actions defined will take effect immediately, not just by pressing the 'Use' button. Also note that it's perfectly safe to disable an Action by switching it to the 'No action' type temporarily -- all the settings of the other types will be kept and don't get lost. There is a mode that helps you finding the corresponding item to an event. By enabling the 'Track incoming events' field, all events from that particular interface will automatically select the last item encountered. Yes, it only shows the last one, especially when a Report contains a lot of triggered events -- but it works rather nicely with keyboards and similar. Finally, there are two buttons that allow you to get to a clean state, labeled 'Fill defaults', removing all user defined Actions and replacing them with their sensible default values) and 'Clear actions', clearing all Actions from a Collection, rendering that Collection dead. I think, that's it. I hope, I haven't forgot to mention something. Thank you very much for reading this long description. But there is so much to fiddle with and so much to do wrong and I'm not at all in the mood of telling everybody, how to use this powerful tool more than once. @endnode @node bootmouse.class "The Bootmouse Class Driver" @{b}--------------------------------------------------------------------------- bootmouse.class ---------------------------------------------------------------------------@{ub} Class: bootmouse.class 1.13 Binding to: interface, classcode 3 (HID), subclass 1, protocol 2 only. Config GUI: seperately for each interface and default class settings. This is a class driver for human interface devices (HID) supporting the so called boot protocol. This can be anything from mice to tablets at allow the use of a pointing device. The bootmouse class only supports the boot mode protocol. This is a standardized protocol that is easy to implement and intended for the PC BIOS, as a general HID driver is much more complex to write and to configure (therefore, bootmouse does not implement the general HID protocol). In this mode, only three mouse buttons and no special features like wheels etc. are supported. V1.11 adds a special experimental wheel mouse support mode (use GUI to enable). This will probably not work with all kinds of mice. Some mice do not send wheel information with boot protocol enabled. Unfortunately, some USB keyboards have multiple interfaces of which some claim to support a bootmouse protocol (which is plain wrong). The data packet is then interpreted as mouse movements, causing some strange things to happen. Normally, this is only invoked by pressing some "special feature" keys on the keyboard. Just avoid them. You may connect or disconnect the device at any time. Be sure to have installed the new @{" input.device " link input.device} to have a 100% compatible mouse replacement. The bootmouse.class can be installed as a @{" RomTag " link romtags}. Due to hardware hacking in the code invoking the boot menu, pressing both mouse buttons on USB mice cannot be used to enter the boot menu without a @{" patch " link bootmenu}. @endnode @node bootkeyboard.class "The Bootkeyboard Class Driver" @{b}--------------------------------------------------------------------------- bootkeyboard.class ---------------------------------------------------------------------------@{ub} Class: bootkeyboard.class 1.13 Binding to: interface, classcode 3 (HID), subclass 1, protocol 1 only. Config GUI: global class prefs This is a class driver for human interface devices (HID) supporting the so called boot protocol. This is normally a keyboard or keypad, but could also be something like the remote control of a beamer. The bootkeyboard class only supports the boot mode protocol. This is a standardized protocol that is easy to implement and intended for the PC BIOS, as a general HID driver is much more complex to write and to configure (therefore, bootkeyboard does not implement the general HID protocol). In this mode, only the normal 104 keys are available, no LEDs are supported. The keys are mapped to the corresponding amiga keys. You might want to load the one of the Win95 keyboard maps found on Aminet to get some of the special keys. Here are differences to the normal Amiga keyboard: F11 -> no effect F12 -> the HELP key (no effect when using ISA keymap) Print -> no effect Scroll -> no effect Break -> ctrl-c Insert -> amiga-c Pos 1 -> shift-cursor left End -> shift-cursor right Page Up -> shift-cursor up Page Down -> shift-cursor down Num Lock -> no effect Menu -> no effect (HELP key, when using ISA keymap) Caps Lock -> Caps Lock until left or right shift is pressed OR Caps Lock until Caps Lock is pressed again (alternate mode) This key layout is static and cannot be changed. Please wait for the general HID class that will add support for anything you want to have. Warning: Pressing the keys ctrl, left amiga and right amiga will reboot the machine. If there are any reset handlers installed, they will be called prior to the reboot. In this case, the reset is delayed by 10 seconds. Starting with V1.9, there is a global configuration GUI. You can change the delay before resetting the machine (will be invoked only, if reset handlers installed) and if the reset handlers should even be used or not. The Caps Lock mode can modified aswell. Also, there's an option to use an alternate keymap, which maps the keys just like standard PC keyboard controllers do. You may also disable the extra key translation (like Page Up/Down, and Break) in this GUI window. You may connect or disconnect the keyboards at any time. Be sure to have installed the new @{" input.device " link input.device} to be able to use the key repeat feature of the OS and have a 100% compatible keyboard replacement. The bootkeyboard.class can be installed as a @{" RomTag " link romtags}. @endnode @node printer.class "The Printer Class Driver" @{b}--------------------------------------------------------------------------- printer.class ---------------------------------------------------------------------------@{ub} Class: printer.class 1.17 Binding to: interface, classcode 7 (printer), subclass 1, protocol 0-1. Config GUI: global class prefs This is a standard class driver for printer devices. Unidirectional and bidirectional printer protocols are supported, the 1284.4 protocol has not been tested yet. On connection of an USB printer, an "usbparallel.device" will be generated run-time. Each printer will get its unit number, starting at 0. If you remove the printer and plug it back in later on, it will get the same unit number it had had before. Keep an eye on the error messages to see which unit is used for which printer. Be aware that no actual printer driver software can be provided. Check the list of drivers available on Aminet or included in OS3.5/3.9 or third party products like TurboPrint, or Studio before you buy an USB printer. Irseesoft has already announced to support more USB printers on the Amiga. In TurboPrint, just enter "usbparallel.device" as the parallel.device to use and select the correct printer driver for it. That's it. Avoid so-called GDI printers. They are cheap, but they are useless without a driver, which is normally only available for Windows. Also, many new printers do not support text printing anymore. The Epson Stylus 870 Photo printer needs a special init-sequence before printing via USB is accepted. The printer.class checks the IEEE1284.4 ID string for Epson printers and automatically sends out this command on connection. If you get a line of strange characters on your Epson printer, disable the Epson init sequence using the GUI. Speaking of the configuration possibilities, some printers crash on receiving the SOFT_RESET command (or do other strange things). If you've got one of these printers, disable SOFT_RESET in the GUI. If you disconnect the printer while printing, all further requests containing the remaining data are sent through hyperspace to an alien lifeform. If you disconnect without a printer job being sent, the usbparallel.device unit will not disappear, but queue all incoming requests (new printer jobs) and wait for you to reconnect the printer. The printer.class can be installed as a @{" RomTag " link romtags}, although this is not really useful (no application I know tries to print something in pre-boot time ;-) ). @endnode @node massstorage.class "The Mass Storage Class Driver" @{b}--------------------------------------------------------------------------- massstorage.class ---------------------------------------------------------------------------@{ub} Class: massstorage.class 1.23 Binding to: interface, classcode 8 (massstorage), subclass 6 (SCSI), protocol 80 (Bulk-only transport), protocol 0 (Control-Bulk (beta)), protocol 1 (Control-Bulk-Interrupt (beta)) Config GUI: Seperately for each interface, some settings per LUN, default class settings This is a standard class driver for mass storage devices (MSD) using a bulk-only transfer and transparent SCSI command set. It is used for storage devices like CF-Readers, ZIP drives, USB harddisks etc. Be aware that not all kinds of protocols are supported yet and there are even (cheap) devices out there which use a vendor specific protocol and therefore cannot be supported. A good indicator for the latter is normally, that you @{i}need@{ui} to install a special driver for Windows/Mac to use the device. Please keep in mind that USB1.1 actually is very unsuitable for high speed transfers. The theoretical transfer limit is about 12MBits/sec, but due to the fact that bulk transfers are limited to 64 bytes packet size, these transfers create a huge overhead. Don't expect much higher transfer rates than 950KB/sec. On the first connection of such an MSD, an "usbscsi.device" will be generated at run-time. Each Logical UNit (LUN) of will get its own device unit number, starting at 0. If you remove the device and plug it back in later on, it will get the same unit number it had had before. Keep an eye on the error messages to see which unit is used for which MSD or LUN. You can then use this usbscsi.device for HDToolBox, for your mountlists or whatever you want to do with it. There is an example DOSDriver included called UMSD. You might have to duplicate it and change the unit numbers to get access to all the LUNs supported by a mass storage device. IMPORTANT: Do not try to mount a unit, if the corresponding usbscsi.device unit is not existant; this will leave you with a non-working DOS entry, unable to remount the device later. Starting with version 1.9, FAT units will be mounted automatically (starting with V1.13, even RDB partitions will be mounted). You do not need any mountlist anymore. Starting with version 1.13, this can be disabled in the configuration GUI. Also, the default name for the FAT partitions can be changed, along with the buffer settings. This GUI also holds fields for the filesystem to use. Finally, some patching can also be applied, including the time to wait before terminating a transfer due to NAK responses (set this value to 0ms to disable NAK timeout). You can also change the default usbscsi.device unit to choose for a LUN here. There are a few more switches, which can help, if your device refuses to work correctly: - Single LUN: Only use LUN0, even if the device has more than one. - No Initial Reset: disable BULK_RESET sending before the first command. If you encounter bulk reset error messages, try this. - Simple SCSI: Filter some scsi commands. If the firmware of the device crashes (NAK timeout), try this. - Translate CMD6->CMD10: Changes some scsi commands to their 10 bytes counterparts. Some broken firmwares cannot handle the 6 byte versions, though they are standard. - Fake Inquiry: Filter the Inquiry command and replace it by an internal routine. - Better Removable Support: Enable this, if your USB device has a good firmware and supports write protection etc. - No Fallback: By default, the MSD class will try to recover from error it encounters by activating some patchflags. You will get some information messages in Trident when this happens. Probably you should then unplug the device and connect it again, and see if it works any better. If it does, save your prefs. - Debug: Enable debug message logging. In the case you found something working with some switches enabled, please don't hesitate to contact me. AutoMounter by Thore Böckelmann is not included anymore in this package. All the features have been incorporated into the class driver based on his sources. V1.15 adds the support to boot from RDB media. You will need to install the stack residently for this to work (see below). The massstorage.class can be installed as a @{" RomTag " link romtags}. @endnode @node cdcacm.class "The Communcation Device Class Driver for Abstract Control Model" @{b}--------------------------------------------------------------------------- cdcacm.class ---------------------------------------------------------------------------@{ub} Class: cdcacm.class 1.6 (beta) Binding to: interface, classcode 2 (Communication Device Class), subclass 2 (Abstract Control Model), protocol 1 (Hayes) Config GUI: none This is a generic class driver for so called 'legacy' USB Modems. It will bind to all modems, which use this ACM standard. Unfortunately, there are several cheap modems out there, which do not conform to this standard. To the AmigaOS the USB device is available through the "usbmodem.device" which is created during runtime and emulates a serial connection. Settings as baud rate, handshaking etc. are ignored. This version is considered beta and some features as break support are missing. The usbmodem.class can be installed as a @{" RomTag " link romtags}. @endnode @node serialpl2303.class "The Serial PL2303 Class Driver" @{b}--------------------------------------------------------------------------- serialpl2303.class ---------------------------------------------------------------------------@{ub} Class: serialpl2303.class 1.8 (beta) Binding to: device, vendor/product: 0x067b/0x2303, 0x067b/0x04bb 0x0557/0x2008 0x04bb/0x0a03 0x6189/0x2068 Config GUI: none This is a class driver for a some USB->serial adapters manufactured by Prolific, Aten and IOData. Please note that it will not bind to or work with other USB products. These adapters can be used to connect standard RS232 devices. To the AmigaOS the USB device is available through the "serialpl2303.device" which is created during runtime. This version is considered beta and some features as break support are missing. The serialpl2303.class can be installed as a @{" RomTag " link romtags}, though this is not very useful except for debugging purposes. @endnode @node rawwrap.class "The RawWrap Class Driver" @{b}--------------------------------------------------------------------------- rawwrap.class ---------------------------------------------------------------------------@{ub} Class: rawwrap.class 1.7 Binding to: either unknown or vendor specific interfaces (depending on the settings) or forced bindings. Config GUI: Both global and individual settings for each interface. The rawwrap.class is a wrapper for some USB device to be accessed via a standard AmigaOS exec device. This allows e.g. the use of USB scanners via BetaScan and might also work with other software like PDA synchronization tools (but this has not been tested). To make this work, the rawwrap.class just allocates the bulk in and out endpoints of an interface. It generates an unit for the usbraw.device and redirects CMD_READ/CMD_WRITE commands towards it. Therefore, if the interface does not have such endpoints, binding to such an interface will fail. However, the rawwrap.class will not bind to any interface by default. You either have to add a @{" forced binding " link tridentdevices} manually or activate the generic binding to unknown (class 0) or vendor specific (class 255) interfaces in the GUI. Speaking of the GUI: There are lots of different options in the GUI to make it as compatible as possible. The Global settings panel only holds two checkmarks to enable automatic bindings to unknown or vendor specific interfaces or even to all interfaces available. Use this with care only, it would be better to use forced bindings instead. The Interface settings contain options to specify the default unit for the usbraw.device and if only one program at a time should be able to use the device. You can both specify the NAK Timeout values for the bulk in and out endpoints. Setting this value to 0 will disable the NAK Timeout feature, potentially keeping the device to wait forever. There are three different modes for the bulk in endpoint: - The 'No Buffering' mode will just convert the read request into an USB request. Is actually might only work with a few programs, but does not require any buffer (therefore, leave the buffer size at 2KB). - The 'Readahead' mode polls the bulk in and always reads as many bytes as there are into the cyclic buffer. It should never loose any packet from the interface (if the buffer is large enough). - The 'Read on request' mode only asks for bytes from the bulk in endpoint when there's a read request from the usbraw.device (but buffers extra bytes internally). Therefore, if the device wanted to send data before that read request and only had a small buffer, data might get lost. In this mode, leave the buffer size at 2KB aswell. The option 'Short reads terminate' will terminate a pending read request whenever a short packet is encountered. This is the standard way of USB devices to signal the end of a transmission. If this checkmark is not set, the command will wait until all bytes requested have been read. For BetaScan, you will need to use the 'Read on request' mode along with 'Short reads terminate' enabled. The rawwrap.class can be installed as a @{" RomTag " link romtags}. @endnode @node hardwaredrivers "Included hardware drivers" @{b}--------------------------------------------------------------------------- Hardware Drivers ---------------------------------------------------------------------------@{ub} The initial Poseidon package only includes hardware drivers for the Highway, Subway and Algor cards. Additionally, a driver for Pegasos onboard USB chipset is available. Other hardware drivers for Thylacine, Amithlon, GRex and other PCI boards are in development by third parties. Hardware drivers are stored in DEVS:USBHardware, just like SANA devices are stored in DEVS:Networks. If you got more than one hardware controller of one kind in your system, the second board should be available by selecting unit 1 etc. Either @{" AddUSBHardware " link addusbhardware} or @{" Trident " link usingtrident} can be used to add the hardware to the system. @endnode @node input.device "MorphOS Input Device V50" @{b}--------------------------------------------------------------------------- MorphOS Input Device V50 ---------------------------------------------------------------------------@{ub} When the original input.device was designed, no precautions were made to support multiple input devices in the means that you should be able to connect as many mice or keyboard or whatever as you like. These are design flaws that cannot be solved without rewriting the original input.device. However, with just a few additions and changes, the WriteEvent interface for external input events can be made to handle most cases. Ralph Schmidt kindly gave access to his sources of the input.device he wrote for MorphOS. So added the context stuff and now it supports the correct handling of external events. Using this input.device you will be able use any keyboard as if it was the original one, including the key repeat feature. The mouse will behave correctly in all the programs. All the problems that had to be fixed with patches like in my tablet driver FormAldiHyd are now obsolete. This is, however, only a temporary solution as the input system of AmigaOS/MorphOS needs to be rewritten with a better design sooner or later. You can install the new version of input.device by adding PsdLoadModule DEVS:input.device QUIET to your startup-sequence before SetPatch, if you have a >=OS3.5 SetPatch, as this will install input.device V50 before SetPatch reboots the machine. One user told us, that he had to place the PsdLoadModule line behind SetPatch, otherwise the machine would hang at the next reboot. Be sure you have the PsdLoadModule program in your C: directory, otherwise adding this line abort your startup-sequence with a "command not found" error. @endnode @node bootmenu "The Boot Menu Patch" @{b}--------------------------------------------------------------------------- Boot Menu Patch ---------------------------------------------------------------------------@{ub} Sorry, the boot menu patch required for AmigaOS versions lower than OS4 is not yet available. The boot menu is fixed with the OS3.9 BoingBag 2. If you can get hold of the contents of this archive, you can use BlizKick by Harry Sintonen to extract the new bootmenu and install it via @{" LoadModule " link loadmodule}. @endnode @node loadmodule "LoadModule and PsdLoadModule" @{b}--------------------------------------------------------------------------- LoadModule and PsdLoadModule ---------------------------------------------------------------------------@{ub} To install Poseidon and its external files as @{" RomTag " link romtags}, a special program is needed. There are at least three different programs that have this capability: - LoadV43Module, unknown author Came with an early beta of the new SCSI-device. Is no longer publically available. - LoadModule by Thomas 'THOR' Richter Available on Aminet, probably part of OS3.5/3.9. No permission was granted to include this program. - LoadModule by Torbjörn Andersson Available on Aminet, included in this archive with permission, has some neat features and it works :) Poseidon initially uses LoadModule by Torbjörn Andersson. Unfortunately, the command name is the same as in THOR's LoadModule. As it possibly is part of OS3.5/3.9, I changed the name to @{b}PsdLoadModule@{ub} not to overwrite an existing LoadModule program -- this is still the program supplied by Torbjörn, not a program by me. If you want to use THOR's LoadModule, just go ahead (only the PsdRomTag script and your startup-sequence need changing). Note that the syntax is a bit different: you have to give the "NOREBOOT" switch, if you don't want to reboot the machine after installing the RomTag. PsdLoadModule only reboots, if you give the "REBOOT" switch instead. @endnode @node romtags "RomTags - How to install Poseidon residently" @{b}--------------------------------------------------------------------------- RomTags - How to install Poseidon residently ---------------------------------------------------------------------------@{ub} The Kickstart ROM of AmigaOS is organized as a set of modules, called RomTags. During booting, each RomTag is called after its priority, possibly loading up or installing libraries, devices and other programs in memory. You can use Scout (see Aminet) to get the list of RomTag in your system. Fortunately, this mechanism can be expanded by installing extra or replacement modules. See the @{" LoadModule " link loadmodule} section on programs that support this. Poseidon and its class drivers don't need many libraries and to be started. Especially, they don't need the dos.library which is available only after the actual boot process. This, however, means that @{b}Poseidon is unable to load anything from disk@{ub}. And that's the reason why all configuration data is stored in just a single file (ENVARC:PsdStackloader), which is actually an executable with attached RomTag. This RomTag will actually boot up the stack and install the configuration. Please note that class or hardware drivers coming from third parties might not be able to be installed residently. So for being reset resident, Poseidon needs the following files to be installed as RomTags: - LIBS:poseidon.library (the main library) - DEVS:USBHardware/#? (the actual hardware driver) - SYS:Classes/USB (the class drivers) - ENVARC:PsdStackloader (the boot strip and the configuration) Installing these files is automatically done by the PsdRomTag batch script located in SYS:Utilities. It will pop up a requester asking you if you want to install or uninstall the RomTags. Note that it will install the current configuration found in ENVARC:PsdStackloader. If you do any changes to this config (using @{" Trident " link usingtrident}), you might want to uninstall and reinstall the RomTags. @endnode @node bugs "Known Bugs" @{b}--------------------------------------------------------------------------- Known Bugs ---------------------------------------------------------------------------@{ub} If you find a bug, please let me know. Give me as much information as possible. Include the outputs of @{" PsdDevLister " link psddevlister} and @{" PsdErrorLog " link psderrorlog}. Known Bugs: - Epson USB printers need a special init sequence. This is sent whenever an Epson printer @{i}(any Epson printer)@{ui} is found. This might cause junk to be printed on USB->Parallel converters on old epson models on the first connect. - CB and CBI transport of Mass Storage Class are not really tested yet. Also have a look at the @{" FAQ " link faq} for more information on bugs and problems. @endnode @node thanks "Acknowledgements" @{b}--------------------------------------------------------------------------- Acknowledgements ---------------------------------------------------------------------------@{ub} Here's a list of (beta) testers, supporters and contributors (in no particular order): Michael 'E3B' Böhmer -- without him, this USB project would never had come to life. More important, he is a good friend and supporter one can trust and rely on. Thanks! Harry 'Piru' Sintonen -- provided me with the cnet.device sourcecode, which I based all my device and library stuff on. This allowed me to write hybrid MorphOS/68k software from the beginning. Ralph 'laire' Schmidt -- for MorphOS and supplying USB hardware to test. Further, he gave me the MorphOS input.device source and allowed me to do the required improvements and include the 68k version for Poseidon. Robert Tsien -- for writing the hardware driver for his Thylacine board, therefore supporting the Poseidon standard. Frank 'cyfm' Mariak -- provided the USB driver for GRex/Pegasos, gave me lots of inputs and suggestions. Felix Schwarz -- for his support in VHI Studio and the constant feedback. Martin 'Mason' Merz -- for his Mason Icons contribution. Good work dude! Torsten Jager -- for his permission to include fat95 and his great work on this software. Check Aminet for new versions! Torbjörn Andersson -- for his permission to include LoadModule, an essential contribution for making Poseidon resident. Thore Böckelmann -- for Automounter. James 'Cyber2th' Albrecht -- for being the biggest pain in the ass, giving me grey hair prematurely, constantly harrassing me, and griping to the point of making me cry. Gunther Nikl -- lots of hints and fixes to the manual and example sources. David 'Zapek' Gerber -- helping hand on obvious bug fixing :) Günther Horbach -- for the provided USB hardware and his patience and faith. I hope I did not forget anybody. If so, please do not be upset, but tell me instead ;-) @endnode @node future "The Future" @{b}--------------------------------------------------------------------------- The Future ---------------------------------------------------------------------------@{ub} There will be a lot of updates! You will find them on my homepage at http://www.platon42.de/ and probably also on http://www.e3b.de/. These updates will also be available on Aminet soon. Here's a list of stuff that is planned for the next releases: - adding workarounds in the class drivers for unusually behaving devices - more class drivers - more third party tools If you've got some good ideas, let me know. @endnode @node faq "Frequently Asked Questions (FAQ)" @{b}--------------------------------------------------------------------------- Frequently Asked Questions (FAQ) ---------------------------------------------------------------------------@{ub} Q: I've connected a flash card reader, but no icon appears on the workbench screen! A: Maybe your card reader does not supported the mass storage class or no filesystem is found on the media. Check, if you have FAT95 installed. See @{" massstorage.class " link massstorage.class} for details. A: Maybe the media is not formatted? Check, if it works on a PC. Q: I've installed Poseidon residently and each time I replug a MSD device, I get the same volume mounted again. A: The @{" massstorage.class " link massstorage.class} was started as a task at boot time. Tasks cannot access the dos.library and therefore are not able to check, if a partition was already mounted. Use PsdRestart to restart the instances so that they are processes, which can use AmigaDOS. Q: It doesn't work. What can I do? A: Provide me with all information you can get (system configuration, what causes the fault, other programs installed, information on the USB device etc.). Run @{" PsdDevLister " link psddevlister} and @{" PsdErrorLog " link psderrorlog}. "It doesn't work" does not actually help me a lot. Q: When I start up the stack with USB devices connected, some don't seem to get recognised and added to the system? A: Sometimes, some USB devices fail to get ready at power-up. Please try disconnecting and reconnecting the device and report this to me. Also watch out for error messages. Q: Keys on my USB keyboard are not repeated when I keep them pressed. Q: MUI drag & drop does not work with my USB mouse. Q: When I click on links with IBrowse, they stay highlighted, but do not work. A: Load up the new @{" input.device " link input.device}. Q: I cannot enter the boot menu with my USB mouse. A: Be sure to have loaded up the new @{" input.device " link input.device}, the stack itself as @{" RomTag " link romtags} and the @{" boot menu patch " link bootmenu}. Q: I have bought some USB device and it does not work! Please write some driver for it! A: If it uses a standard class, provide me with all the information you can get about it. If it uses a vendor specific protocol, there is not much I can do. Moreover, the list of "unusual devices" is very long. I cannot write workarounds for bugs in all firmware of those broken devices. @endnode @node devdocs "Developer Docs" @{b}--------------------------------------------------------------------------- Developer Docs ---------------------------------------------------------------------------@{ub} There is a lot of developer material available, but due to the speed the software developed, it is currently not quite up to date and needs to be extended before it can be published. I apologize. The material will be publically available as soon as the new version is finished, but the old version may also be requested via @{" email " link contactaddress}. @endnode @node history "Version History" @{b}--------------------------------------------------------------------------- Version History ---------------------------------------------------------------------------@{ub} poseidon.library 2.2 o Querying DA_CurrCfg now calls the USB command to be sure that the current config number is up to date (suggested by Uwe Ryssel). Removed that again, because he reported it to be of no use. o Fixed a race condition for interface and device bindings. Caused some havoc on my Pegasos with four root hubs during PsdRestart. o Added Epson mass storage interface patch for printers with card slots. o Poseidon no longer ignores configurations, if the config was set without error but nevertheless returns a bad GetConfiguration number. Fixes problems with broken Olympus cameras. o Implemented DA_CloneCount. Mounting two devices with exactly the same VendorID, ProductID and serial number will give it a unique clone count number (e.g. required when plugging in two joypads from the very same vendor -- this still allows different prefs for the second one). o Due to popular demand, the "welcome" line has been cosmetically fixed. o Now generates more meaningful names for the device name according to the interface class, if the device cannot say its name itself. o Empty device descriptor strings are now considered to be invalid. Trident 2.0 o More rewriting for subclasses. o Lots of internal changes, I cannot remember. o Lots of fixes for the subwindow handling. o Automatic updating works again. o Reintroduced Poseidon-Logo to USB.mprefs. o Generally, more robust. o Added Online/Offline menu items. Installer script 1.8 o Added spanish installer strings and licence translation courtesy of Dámaso Domínguez. o Small changes for better ArakAttack support. serialpl2303.class 1.8 o Added detection of Sitecom serial adapter (reported by Jens Bagh). rawwrap.class 1.7 o Added default settings for epson scanners, as requested by FelixS. massstorage.class 1.23 o Simple SCSI patchflag now disables geometry scan. o Added two new GUI option for patchflags. o Fixed a misplaced CloseLibrary() reported by jacaDcaps o Improved fssm check as suggested by Heinz Wrobel. o Changed default settings to CMD6->CMD10, no initial reset and simple SCSI. hid.class 1.6 o Restricted assignment of mouse buttons and pointer movement to mouse and tablet items (connecting joypads don't block the mouse anymore). o Raw keymap strings enhanced to be user readable and more friendly. o Added missing keyboard mapping stuff. o Added option to disable all actions. o Added option to show the current values of an item. o Added absolute to relative value translation (i.e. for joypads and tablets). o Added clipping of values. o Added scaling of values. o Added pre-condition codes for actions (you probably do not grasp the power that's behind this tiny line, but just read the manual). o Added input redirection for action values. o Added optional tracking of key events for keyboard mapping. o Generated default actions for joypads. o Added patching of lowlevel.library/ReadJoyPort() for digital joystick emulation (works great on MAME). o Added a button to copy an existing action (might come in handy). o Introduced a new trigger if the value returned was out of bound (needed for hatswitch, stupid stupid design flaw of the HID specs IMHO). o Added default actions for digital pads (hatswitches). o Added default actions for analogue sticks. Warning: if you have got a joypad with hatswitch (digital pad), you need to disable the hatswitch default actions, because they will interfere with the analogue stick handling (or use another port for it? :) ). o Added a column for the current/last value in the items list. It does not get updated automatically, except for the selected item, if you enable "Report current values". o Optimized action updating process when switching between two items (e.g. in track events mode). o Fixed reading of item arrays that were not one or eight bits wide. Obviously, this code was never used (as I did not encounter one device yet that uses arbitarily sized items for an array). o Added output and feature items and actions! Yay! This means you can now toggle the leds on a keyboard, toggle the force feedback (rumble) of a joypad, send out all kinds of data to the device. o Added default actions for caps lock led. o Added a new report/collection with two items to add actions on connection and disconnecting (i.e. variable initialization or sound playback). o Lots and lots of internal changes I cannot quite remember. o Source code for the HID class is now about 450 KB, just to get the picture. o Last Action Hero subtask is now created on demand. This fixes the problems (reported by Hartmut Schulze) of the task not being generated at boot point (FlashRom), due to the lack of some of the required libraries. printer.class 1.17 o Accepts now short packets on recieving without outputting an error message. AddUSBClasses 1.3 o Now searches in MOSSYS:Classes/USB instead of SYS:Classes/USB, if found. AddUSBHardware 1.5 o Added an ALL option. When used for adding hardware, all units are added until one fails. When used on REMOVE, it removes all active USB controller hardware, effectively switching off the stack. AddUSBHardware 1.4 o On removal, checks only the given device name and not the path as requested by Günther Nikl. algorusb.device 1.7 o Fixed a bug with packet size calculation on interrupt endpoints with MaxPktSize != 2^x. Sorry!!! o Optimized interrupt ETD allocation. Turned on immediate interrupts for all endpoints. This should stop the performance loss some people have reported when connecting hubs. PsdDevlister o Now also returns IDStrings for Devices and Interfaces. o Properly reports Application Bindings. o Outputs a google search line ;) o Replaced printf by Printf (smaller binary). --------------------------------------------------------------------------- Trident 1.5 o Large rewrite for USB.mprefs for MorphOS. Some features were missing, such as automatic updating. subwayusb.device 2.7 o Fixed a stack overflow condition due to the increased memory usage and a local dummy struct in the OpenUnit() code. o Fixed a problem with the interrupt code (introduced probably with V2.5 or V2.6). massstorage.class 1.21 o Mode page reading routine rewritten. o GetGeometry completely rewritten. Fixed several bugs. Returns now nice values for all kinds of missing values. o Detects write protection change even if no disk change occurs. --------------------------------------------------------------------------- poseidon.library 2.1 o Added psdCheckPipe() requested by UltraGelb. o psdFindInterface() now can find alternative interfaces (also requested by UltraGelb). o Now also returns truncated string descriptors instead of returning an error. Trident 1.4 o Added warning for forced interface bindings, too. o DevClass shown is now acquired from the interface classes as people have difficulties understanding that 'None' at DevClass is nothing bad. Also, replaced red exclamation mark by blue question mark. hid.class 1.5 o fixed wrong mapping of numeric + as reported by Bernd Gollesch. o no delta movements do not cause mouse movement events anymore, as requested by FelixS. This also fixes the problems with YAM2.4 under MorphOS. o 'Track incoming events' does not jump back to the zero value, as some devices have zero as a valid item number in array, which actually is out of range. hub.class 1.21 o Slight changes not to hang with broken hubs that NAK forever. o Will now correctly detect the removal of device shortly after plugging a device in. massstorage.class 1.20 o Tweaked CBI even more. o Fixed and improved write protection check, I messed up in V1.19. I'm very sorry the inconveniences I caused. o Enabled NAK Timeout for initial GET_MAX_LUN request, because some devices NAK forever here. o CreateSegment() was still bugged in the rare case that the segment wanted chip mem (which shouldn't happen with filesystems anyway). o Cylinders from Rigid Disk Geometry Page was not read correctly. o Fixed a potential division by zero in geometry calculation. o If a protection change is detected, a diskchange is now invoked to the unit. highwayusb.device 2.12 / subwayusb.device 2.6 o Undone little changes from V2.11, increased priority of interrupt handler again, although I'm not sure what the problem was. o Toggle bits are now handles separately for in and out on the same endpoint. There are some devices out there which use the same endpoint for data transfers in both directions, causing the toggle bits to get out of sync. This is a violation of the usb spec, so consider this a workaround for buggy devices. o Fixes to ISO IN error cases. o ISO IN now also allows more than one packet per request to be received. o more little changes. algorusb.device 1.6 o Various fixes. UproarTool 1.0 o Initial. DRadioTool 1.1 o Initial. --------------------------------------------------------------------------- poseidon.library 2.0 o Bumped version to 2. This mainly is due to the anniversary. o If device enumeration failed, the assigned usb device address was not freed. o During enumeration, the pipe for the target device address was not set to 0. This caused SET_ADDRESS timeouts on retrying the enumeration. Fixed. hub.class 1.20 o Fixed wrong GET_STATUS request (non zero wValue). massstorage.class 1.19 o Fixed zillion of bugs in CreateSegment() by Ralph Schmidt ;) o When using SimpleSCSI, protection is not queried anymore. o Fixed CB/CBI protocol. I hope, I didn't break other devices, but at least now the MP3 Player sent in by Oliver Mart works. Did I mention that CB/CBI is really a brainf*cked transfer protocol? o Fixed AutoMount crashing, if evil DosList entries are found (thanks to Olli & Laire). o Deactivated Command Status Block Signature check for Olympus cams, as they are broken. o Protection is also updated on each mode sense request. o Fixed CB/CBI transport even more. o Fixed support for UFI command set. USB Floppy drives should work now! o Now the first block is checked for a valid filesystem entry aswell to allow mounting of floppy disks (and similar media without MBR). Trident 1.3 o Added balancing bar for information list view (requested by Henes). o Will not attempt to run ENV:PsdStackloader anymore with HappyENV installed (because HappyENV has no executable bits set). o Added a warning requester for forced device bindings. hid.class 1.4 o Fixed resident tag. Now automatic switching from bootmouse/keyboard to HID class on PsdRestart in FlashRom actually works. o Help key on USB keyboards was not assigned to help in the AmigaOS (reported by FelixS). all classes o Fixed a potential crash under MorphOS when using multiple MUI windows. o Potential danger when attempting to abort quick commands fixed. PsdRestart 1.2 o Fixed resident tag. o Will now output a message into the errorlog. algorusb.device 1.4 o Initial. DRadioTool 1.1 o Initial. UproarTool 1.0 o Initial. --------------------------------------------------------------------------- poseidon.library 1.33 o No change, just bumped revision. Trident 1.2 o Fixed a wrong format string causing an enforcer hit under MorphOS (only, as the code triggered some locale specific stuff). o Changed a gadget label. hub.class 1.19 o Packet overflow on GET_HUB_DESCRIPTOR is now ignored. Fixes a broken LG Monitor hub firmware. hid.class 1.3 o Get HID descriptor is retried once on request of Stefan Burstroem. o Packet overflow on GET_HID_DESCRIPTOR is now ignored. Fixes a broken LG Monitor hub firmware. o Failure of setting report type does not bail out anymore. Fixes a broken LG Monitor hub firmware. o Done a workaround to avoid MUI writing into the resident module, that would crash the GUI when MuProtectModule was active. Note: This is actually a MUI bug (or flaw). o Track incoming event now works better on variables. o Fixed an order problem with the qualifier actions that could cause repeated keys. Note: you will have to 'fill the defaults' for keyboards again, if you saved some interface prefs. massstorage.class 1.18 o Done a workaround to avoid MUI writing into the resident module, that would crash the GUI when MuProtectModule was active. Note: This is actually a MUI bug (or flaw). o Added more debug information. --------------------------------------------------------------------------- poseidon.library 1.32 o Fixed a 'minor' enforcer hit introduced in V1.31. o Added even more vendor strings. o Added support for forced bindings. o Special Elb*x driver treatment implemented. o Various small fixes and tweaks. Trident 1.1 o Added support for forced bindings, both for whole devices or single interfaces. They can be set using a context popup menu in the device or interface list views. Warning, this is an advanced user option, using it the wrong way may render your devices useless, until you remove the forced binding again. o Removes .elf-extension on DirScan before trying to add that class. o Uses full path SYS:Classes/USB/ instead of only USB/ now. o Fixed a race condition that could cause a recoverable 01000008 guru on deletion of a hardware entry. o Saving the config to ENV:PsdStackloader showed an error if there was none and vice versa (just forgot an '!' in the source :( ) (reported by Erik Johansson). AddUSBClasses 1.2 o Removes .elf-extension on DirScan before trying to add that class. o Uses full path SYS:Classes/USB/ instead of only USB/ now. hid.class 1.2 o Initial. About ~9000 lines of code (>300KB source code). Lots of features, some are still missing. Depressingly long manual. Great loss of hair. Surprisingly much fun. Enjoy. rawwrap.class 1.5 o Initial. Class for wrapping bulk in/out endpoints of an interface to usbraw.device. Can be used for BetaScan, maybe for some other programs aswell (like Spitfire). bootmouse.class 1.12 o Forgot filling in the devid and ifid string pointers, therefore failed to load previously saved configuration and caused an enforcer hit. massstorage.class 1.17 o Added default unit GUI setting. o Added mode (and GUI patchflag) to translate READ_6/WRITE_6, MODE_SENSE_6, MODE_SELECT_6 to their 10 bytes equivalent. This might help to fix broken devices. o Added debug flag, that will output a few more lines of information. o Fixed a bug that could potentially assign the same unit numbers to different LUNs (that probably did never appear before though). o Buffers setting wasn't saved. Fixed (reported ex-post by Ch. Sauer). o There was one (!) static variable that killed the class when used residently with LoadModule by Thor due to a wrong checksum. Fixed (reported by Ch. Sauer). o Now also sets Reserved = 1 for mounting FAT partitions. This allows the use of CrossDOS (suggested by Ch. Sauer). o Returns the size of the data transferred in io_Actual, although this is not mandatory according to the AutoDocs, but some programs (e.g. ScsiSpeed seem to rely on this). o Oops, slight change of code caused the last LUN settings to overwrite all other LUN settings (reported by Erik Johansson). Fixed. subway.device 2.4 o Fixed clockport detection. o Fixed some bugs (most of them introduced with this version). highway.device / subway.device o Interrupt requests with iouh_Length > iouh_MaxPktSize would never return, if all packets were of iouh_MaxPktSize. o Increased reading speed for bulk transfers by about 40% (at least here on my machine) by changing the order of some code. DriveSpeed reports about 735000 bytes/sec for the ZIP250 on Highway. o Further code optimizations. serialpl2303/rawwrap/printer/massstorage/cdcacm.class o AbortIO() was broken for more than one read/write request pending, I forgot to walk the linked list in the loop :-\ (reported by Svend Daugaard Pedersen). all classes o Bailing out of a class binding on early binding failure was broken (this was the very last time you will see this message). o Ooops. GUI exit code forgot to dispose the MUI objects. --------------------------------------------------------------------------- poseidon.library 1.31 o Added stack config support. Trident 0.12 o Added stack config stuff. o Misc changes. hub.class 1.17 o Fixed a bug where the hub task wouldn't neccessarily fail out from the outer loop on hub removal. bootmouse.class 1.11 o Added experimental quick & hacky wheelmouse support. Will probably only work with a few mice (the ones that report wheel movement in byte 4 even with boot protocol enabled -- works with my Sigma mouse, doesn't work with my Logitech wireless desktop (no wheelmouse data in boot protocol). Be sure you have MUIWheelPatch installed. o Added class (defaults) and binding GUI to enable wheelmouse support. massstorage.class 1.15 o Booting from RDB implemented (added a flag for this in the GUI aswell). Thanks to Ralph Schmidt for contributing the CreateSegment() code. o Misc internal changes. o RDB Mounting added. Now RDB formatted partitions will be mounted automagically on media insertion aswell. o Mounting is not done from the device task anymore (as this could cause a deadlock, if the filesystem wanted to do device IO before returning from the mount call), but from a tiny seperate task, living only for the moment :) o Changed implementation of FIX_INQUIRY to fake inquiry. Old fix inquiry is still present for wrong inquiry requests. Fake Inquiry should fix a lot of broken devices. o Added option to disable the initial bulk reset, as some broken devices seem to choke on it (and crash their firmware, stupid thing). o Changed NakTimeout prefs value from ms to 1/10secs. This seems more reasonable. Please check your configs. o Added option to delay the device startup. This is needed for some broken devices, which crash their firmware, if they receive commands during their setup (Nikon Coolpix). o Added possibility to change the DOSType. If the DOSType is NOT 0x464154xx (FATx), LowCyl will not be 0 and autodetection of FAT95 will be disabled. This should allow the use of CrossDOS, but this has not been tested. o Added saving of default prefs. o Added default prefs GUI (class config). printer.class 1.14 o Added implementation of CMD_START/CMD_STOP. o Added class GUI with two options: one disables the sending of the init sequence on Epson printers, the other one disables the SOFT_RESET command which causes problems on some broken printers. --------------------------------------------------------------------------- poseidon.library 1.30 o psdFreeVec() was broken (freed 4 bytes less than allocated). I am really sorry about this. Pfuschwork orange. o Added class config reading and writing. o Added interface/device config reading and writing. o Added some more support functions to the library. o Internal variables/flags added for USB2.0 support (although, there is no working USB2.0 support right now). o Added NAK timeout (5 secs) on EP0 while enumerating, as there seem to be badly broken devices out there, doing NAKs forever, blocking out the stack until the device is removed again. o There were some global fields in the library data section which caused LoadModule by THOR to remove the resident tag because the checksum was wrong. Hopefully, this is now fixed. o Licence check was broken. I forgot an if-clause, which caused the single user keyfile being killed after the verification (i.e. click on online/offline/online and you were back to demo version). Sorry to Mediator users. Trident 0.11 o Added calls to open class config windows. o Fixed some gadgets in device window not being ghosted. o Added 'Settings' gadget in device window. o Added speed output of USB 2.0 highspeed devices (no support in the stack, yet). o Added calls to open binding config windows. o Added some gadgets in device info window. o Increased stack to 16KB as it was nearly running out of stack. all classes o Lots of internal changes to be more extensible (via a DoMethod vector). o Changed classes to use the new FindEndpoint and FindInterface support functions. Saves a few bytes, makes classes more robust. o Bailing out code introduced with release V1.27 was broken and would always have crashed the machine on failing allocation. Fixed. massstorage.class 1.13 o Bugfix: With a device with multiple LUNs, Permit() was called more often than Forbid(). Could have caused all kinds of havoc. Fixed. o Data overflow is now being ignored in the data phase. This fixes some broken devices. o Added device config GUI. I hope you enjoy it. If there's something missing, please let me know. Remember that automounting of RDB partitions still doesn't work, even if there's a switch already. o On response timeout errors and multiple LUNs, access to unit could be locked, hanging the other LUN tasks. Stupid bug, which is now fixed. o CB/CBI recovery handling didn't work in some cases. o Added CBI_RESET (maybe this helps?). bootkeyboard.class 1.9 o Added class config GUI. The configuration settings include turning on/off of ResetHandlers, setting the time until the machine reboots (in case of resethandlers installed) and an alternate caps lock mode. o Added ISA keymap option, aswell as an option to disable the extra key translation functions (like page up/down). o Extra key translation did not send events for up-qualifiers, therefore shift (or amiga or control) were still pressed after using keys like page up/down. Fixed. highway.device subway.device o Fixed a possibly wrong PPC gate function. --------------------------------------------------------------------------- poseidon.library 1.28 o BrokenConfigFix: Sony Handycam has a wrong MSD subclass. o BrokenConfigFix: LaCie USB Floppy drive has a dummy interface. o Internal changes to accept user keyfiles. o Added restarting function. AddUsbHardware 1.2 o Did not call psdEnumerateHardware() when using QUIET. Fixed. Reported by Christian Sauer, thanks a lot. PsdRestart 1.1 o Initial. pencam.vhi 1.2 o Initial driver for VHI Studio. PencamTool 1.6 o Optimized bayer derasterization function. o Derived pencam.vhi driver from PencamTool. Trident 0.9 o Added hardware driver information window. o Added menu item to inject user keyfile. all classes o Fixed them to compile for MorphOS. highwayusb.device 2.9 o Slight changes for compiling for MorphOS. subwayusb.device 2.3 o Slight changes for compiling for MorphOS. --------------------------------------------------------------------------- poseidon.library 1.27 o Internal changes for PPC native compile. printer.class 1.11 o Fixed printes with twisted bulk in/bulk out. Should have been more careful with this from the beginning :-\ all classes o Bailing out of a class binding on binding failure was broken. --------------------------------------------------------------------------- poseidon.library 1.27 o Internal changes for PPC native compile. printer.class 1.11 o Fixed printes with twisted bulk in/bulk out. Should have been more careful with this from the beginning :-\ all classes o Bailing out of a class binding on binding failure was broken. --------------------------------------------------------------------------- poseidon.library 1.26 o On USB devices with multiple configurations, only the first one was read due to me thinking that I would get all configurations automatically. This is now fixed. Hey, it was the first time I came across a device with multiple configs, so I couldn't test the code before. massstorage.class 1.11 o Added information messages on mounting (after three attempts :) ). o Mounting now again uses lowcyl = 0. But therefore, detection of an already mounted partition has been reduced to unit, device and dostype. This means that no multiple partitions on a harddisk will be mounted, but only the first one. I hope this is not a problem for most of you. (thanks to Jens & Jean-François). o After mounting, a diskchange signal was sent. This is now fixed (thanks to Jens). o Added NSD and TD64 support. This means you now can uses harddisks >4GB. serialpl2303.class 1.3 o Fixed buffer management. Added EOF mode. cdcacm.class 1.2 o Initial. Should support state reporting and EOF mode. --------------------------------------------------------------------------- pencamtool o Added UPTO option. highwayusb.device 2.8 o Optimized copyloop a bit. subwayusb.device 2.2 o Initial serialpl2303.class 1.2 o Initial bootkeyboard.class 1.6 o Now calls reset handlers of the keyboard.device on reset. This is done in a tricky, but system-friendly way. If any reset handler is found, the reset is delayed by 10 seconds (no way to find out, if the reset handlers have finished). massstorage.class 1.9 o Added 200ms delay for some strange devices before first interaction. I hope this is enough for most drives. o Added automounting capability for FAT95. Took me ages to get this working. Sorry. o Added experimental untested support for CB and CBI transport protocols. o Added special init sequence for eUSCSI bridges. o Disabled internal retry mechanism for HDCMD_SCSI commands. Maybe this fixes the disk changing bugs when using "+s" on FAT95. o Fixed broken disk change detection. Sorry, just forgot some paranthesis. hub.class 1.14 o Changed the init sequence to be more error tolerant, adding several retries o Added locking mechanism (oops! how could I forget) of address 0 to avoid confusion on the bus with multiple hubs connected to a hub at the same time. o Lots of little changes. poseidon.library 1.25 o If SET_CONFIGURATION fails, the enumeration will now still proceed. This seems to be the case with a few USB2.0 devices. o Changed psdSpawnSubTask() to launch a process if started with dos available. o Misc little changes. @endnode @node contactaddress "Contacting the Author..." @{b}--------------------------------------------------------------------------- Contacting the Author... ---------------------------------------------------------------------------@{ub} Feel free to contact me, if you have any questions or if you want to get the developer pack. There is also a mailing list for developers, contact me, if you want to be included. Chris Hodges Account: 359 68 63 Kennedystr. 8 BLZ : 700 530 70 D-82178 Puchheim Bank : Sparkasse Fürstenfeldbruck Germany Tel.: +49-89/80001543 WWW: http://www.platon42.de/ Email: hodges@in.tum.de IRC: platon42 on EfNet/Arcnet @endnode