@database Poseidon-Manual @author "Chris Hodges" @$VER: Poseidon V2.0 (14-Oct-14) @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: 4.5 (14.10.14) @{fg shine}| __ ( @{fg text} Designed and written by Chris Hodges. @{fg shine}|"(__) )@{fg text} @{fg shine}|_____/ @{fg text} Copyright ©2002-2014 @{" Chris Hodges " link contactaddress}. All rights reserved.@{ub} WARNING: @{b}Read @{" this " link legalstuff} first before using this software!@{ub} --------------------------------------------------------------------------- @{" Legal Issue " link legalstuff} @{" 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} @{" FrequentlyAskedQuestions " link faq} @{" Contacting the Author " link contactaddress} @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-2014 by Chris Hodges. All rights reserved. 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}Terms of use@{fg text}@{ub} @{b}---------------------------------------------------------------------------@{ub} No parts of this program or documentation may be altered by any means (this includes editing, modifying, reprogramming, extracting, crunching, resourcing etc.) except archiving. @{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. 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. @{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. 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 license conditions.@{fg text}@{ub} @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 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 - A USB hardware controller and its hardware driver - Devices with USB interface ;-) - MUI for the Trident GUI or - MorphOS 1.4 (V50) or higher - PPC603e or higher - About 300KB free memory - A 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 USB hardware controller and its hardware driver - 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 ;-) @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, printers and mass storage devices will be usable immediately. @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 seven panels: @{" General " link tridentgeneral} @{" Controllers " link tridenthardware} @{" Devices " link tridentdevices} @{" Classes " link tridentclasses} @{" Options " link tridentoptions} @{" Popups " link tridentpopups} @{" 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 a 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 save in the list of error messages for bugreporting, there is a 'Save to disk' button. To remove all current messages from memory, click on the 'Flush all' gadget. You can also disable the generation of messages in the @{" Options panel " link tridentoptions}. @{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. @endnode @node tridentgeneral "Trident General Panel" @{b}--------------------------------------------------------------------------- Trident General Panel ---------------------------------------------------------------------------@{ub} Not much to see here except for a nice Poseidon logo. @endnode @node tridenthardware "Trident Controllers Panel" @{b}--------------------------------------------------------------------------- Trident Controllers 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). @{b}--------------------------------------------------------------------------- Device Information Window ---------------------------------------------------------------------------@{ub} 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. Moreover, you can change the name of the device that is displayed in the Trident window (and information messages) by entering a new name in the "Custom Device Name" field (press the return key or "Change Name" button to confirm). This makes sense, if the device name is something cryptic and not a nice human readable string. To restore the original name, click on "Restore Name". By selecting "Disable class bindings", you can exclude this device from the class scan. This allows applications or custom drivers to bind to the device, even if it normally would be taken by a standard class. If "Inhibit popup" is activated, any normally appearing pop up requesters will not be shown at all (not even for errors). This is the default for hubs (especially because the root hub messages are a bit useless). The "Power Info" field determines, if Poseidon should believe what an USB device says about its own power consumption. Unfortunately, a lot of devices, especially hubs, return incorrect data, making the power manangement and low power warnings useless. I've got only one hub that correctly sets the "self-powered" and "bus-powered" attribute correctly depending on whether an external power supply is used. So, if you've got a hub without external PSU, but it's listed with "self-powered", you'd better override the "Power Info" setting to the correct value. @{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 a 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 tridentoptions "Trident Options Panel" @{b}--------------------------------------------------------------------------- Trident Options 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: Stack config: - 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 a 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. - Automatically disable hub port on low power conditions: If this option is set, low power conditions that were indicated by the USB device's own information, will disable the offending device immediately. Unfortunately, a lot of hubs and devices don't tell the truth about their power consumption, or being bus- or self-powered. Use this switch with care and change the power information in the @{" Device Window " link tridentdevices} accordingly for devices spreading lies. - Automatically disable hub port, if device drops dead: Poseidon may detect devices that have crashed and stop responding to USB requests in a normal way by disabling them immediately. Select this checkmark to enable the feature. - Enable power-saving suspend mode: All USB device must implement a suspend mode where their power consumption is reduced to less than 1mA. This is a lot less than the 100mA or 500mA (2.5 watts) a device may use during normal operation. For normal desktop PCs, this may not be of importance, but for mobile or battery powered machines (like an EFIKA placed in your favourite car) this is cruicial. Anyway, it's good to save some power for environmental reasons. If this option is enabled, a USB device will be placed automatically into suspend mode, after some time of inactivity -- if the USB class driver supports suspending. USB devices may support a feature called "remote wakeup". In this case, the device may resume operation on its own (usually mice and keyboards support this). Unfortunately there may be some devices which say they support remote wakeup, but they don't. I have at least one keyboard with this kind of suckage. In this case, you should disable power-saving. The device will also automatically be resumed on I/O operations by the stack. Resuming a device normally takes less than 25ms. - Force suspend mode, even if not supported by class: As not all classes currently have support for suspending built-in, you may enable this switch which will even suspend devices without explicit support. This may or may not work very well. If there is pending I/O, it will release the binding instead (only if remote wakeup is available, otherwise the class won't be able to detect that it should resume operation). - Inactivity timeout for suspend: Defines the time of inactivity that is needed for a device before going into suspend. Logging Options: 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 tridentpopups "Trident Popups Panel" @{b}--------------------------------------------------------------------------- Trident Popups Panel ---------------------------------------------------------------------------@{ub} Poseidon V3.x comes with some new annoying information windows as found on other popular operating systems. The Poseidon Popups, or in short PoPos are usually of more use. If you don't like them, these options will come in handy. Please remember that you can exclude individual devices from popping up at all by selecting the "Inhibit popup" checkbox in the @{" Device Information Window " link tridentdevices}. - On Connecting: Determines the behaviour of the popup windows on connecting a USB device in different grades of annoyance. I think the different options are self-explaining. - On Disconnecting: If enabled, Poseidon will show a popup, when a device is removed. This information is probably totally useless as the user knows what he has done, but hey maybe that's just to show that the computer is not completely dumb. - Popup delay: Determines, how long the Popup window should be displayed before disappearing automatically again. Set this to 0 make the window stay until you close it manually. You can also stop the requester from disappearing by enabling the "Hold on" gadget in the window itself. - Activate window: One thing that makes these popups on other operating systems so annoying is that the window gathers the input focus, even when you were just typing something in another program. If this option is disabled, the popup window will not be "activated", it will not get the input focus automatically. - Pop to front: If selected, the window and screen will pop to front on opening. - Connection sound: The soundfile given in this gadget is played back, whenever a device is connected, regardless of the "On Connecting" behaviour. If you don't want to have a sound here, leave the gadget empty. The file must be loadable by datatypes to be played back. - Disconnect sound: The soundfile given in this gadget is played back, whenever a device is removed from the system, or an error condition occurs (like death or low power) regardless, if "On Disconnecting" is checked or not. If you don't want to have a sound here, leave the gadget empty. The file must be loadable by datatypes to be played back. @endnode @node tridentconfig "Trident Config Panel" @{b}--------------------------------------------------------------------------- Trident Config Panel ---------------------------------------------------------------------------@{ub} This panel is used for configuration management. The main listview shows a list of most configuration data currently stored in the prefs file (ENVARC:PsdStackloader on disk). Drag'n Drop can be used to duplicate or overwrite compatible prefs between two devices. Only sensible operations are allowed (e.g. replacing the prefs of a USB device with the ones from another USB device, or copying interface config to a device etc.). The "Save as" button allows to save the whole config to a file, just like the item from the menu. The "Export" function saves the selected part of the prefs into a file for later reimporting or exchange between different users. The "Import" button will pop up a file requester asking you to import a config file. For interface or device configs you need to select the device to add them to beforehand. To remove an obsolete or unnecessary part of the prefs, click on "Remove" with the objecting line selected. Note that this will automatically restore the default prefs for a class or device the next time you connect it. @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 - @{" SonixcamTool " link pencamtool} -> Versatile webcam utility - @{" pencam.vhi " link pencam.vhi} -> Pencam VHI Studio driver - @{" sonixcam.vhi " link pencam.vhi} -> Sonixcam VHI Studio driver - @{" DRadioTool " link dradiotool} -> D-Link/GemTek USB radio tool - @{" RocketTool " link rockettool} -> Control a USB Rocket Launcher - @{" PowManTool " link powmantool} -> Tool for USB Power Manager Outlets - @{" PsdRomTag " link romtags} -> Install/uninstall Poseidon residently @endnode @node addusbhardware "AddUSBHardware" @{b}--------------------------------------------------------------------------- AddUSBHardware ---------------------------------------------------------------------------@{ub} Command : AddUSBHardware 1.6 Template: DEVICE,UNIT/N,QUIET/S,REMOVE/S,ALL/S Examples: AddUSBHardware DEVS:USBHardware/rapidroadcpusb.device AddUSBHardware DEVS:USBHardware/rapidroadxs100usb.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.5 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 3.0 Template: SHOWROOT/S,QUICK/S,STRINGS/S 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. Usage: SHOWROOT/S - Normally, the root hub(s) are excluded from the output, as they don't contain valuable information. Specify this switch, if you really want to see it. QUICK/S - If given, omits some output, decreasing verbosity. STRINGS/S - Tries to read out a list of string descriptors the device contains, might cause some devices to crash, hence this is disabled by default. @endnode @node psderrorlog "PsdErrorLog" @{b}--------------------------------------------------------------------------- PsdErrorLog ---------------------------------------------------------------------------@{ub} Command : PsdErrorLog 3.0 Template: NOFLUSH/S,DEBUG/S 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. Usage: NOFLUSH/S - If given, outputs the errors without discarding them. DEBUG/S - Prints some additional debug information. If Poseidon ever seems to hang, include the output of PsdErrorlog with DEBUG enabled. @endnode @node psdrestart "PsdRestart" @{b}--------------------------------------------------------------------------- PsdRestart ---------------------------------------------------------------------------@{ub} Command : PsdRestart (obsolete) 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 was to restart the subtasks that were created during boot time as dos.library aware processes. As both the hid.class and the massstorage.class now automatically adapt to the existance of the dos.library, this command has become obsolete. PsdRestart no longer 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 a 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 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 sonixcamtool "SonixcamTool" @{b}--------------------------------------------------------------------------- SonixcamTool ---------------------------------------------------------------------------@{ub} Command : SonixcamTool 1.6 Template: TO/A,INTERVAL/N,UPTO/N/K,GAMMA/K,SHARPEN/S, TEXT/K,FONT/K,FONTSIZE/N/K,UNIT/N/K Examples: SonixcamTool Snap.ppm SonixcamTool Snap.ppm GAMMA 0.45 SHARPEN SonixcamTool Movie%04ld.ppm INTERVAL 0 GAMMA 0.5 SonixcamTool Webcam.ppm GAMMA 0.45 SHARPEN TEXT "Platon's Cam" FONT small.font FONTSIZE 6 SonixcamTool Shotseries%03ld.ppm INTERVAL 0 UPTO 79 GAMMA 0.45 SHARPEN Purpose: Command line tool to read out images from a USB webcam using the Sonix Technologies chipset (Vendor ID = 0x0C45) with OV7630 sensors. This includes the cheap webcams with bendable metal cord found e.g. at www.pearl.de and probably a lot more 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. Warning: SonixcamTool only works with host controllers that support realtime iso transfers. 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. INTERVAL/N - if this numeric parameter is given, SonixcamTool will loop and take pictures at the given interval (in ticks, 50 ticks is one second). Use Ctrl-C to abort the SonixcamTool. UPTO/N/K - if specified, multiple pictures can be grabbed in one go, stopping after the UPTO pictures. Be sure to give a format string such as "%ld" inside the filename or you will write all pictures to the same image. Only useful together with INTERVAL. 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 sonixcam.vhi "Sonixcam VHI Studio Driver" @{b}--------------------------------------------------------------------------- Sonixcam VHI Studio Driver ---------------------------------------------------------------------------@{ub} File : Libs:VHI/sonixcam.vhi Version: 1.0 Purpose: This is a VHI Studio driver for the Sonixcam series. It allows to take snapshots of the images from USB webcams using the Sonix Technologies chipset (Vendor ID = 0x0C45) with OV7630 sensors. Warning: sonixcam.vhi only works with host controllers that support realtime iso transfers. 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 have the possibility to take snapshots. You can create some animations at upto 12 fps. @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 a 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 rockettool "RocketTool" @{b}--------------------------------------------------------------------------- RocketTool ---------------------------------------------------------------------------@{ub} Command : RocketTool 1.1 Template: LEFT/S,RIGHT/S,UP/S,DOWN/S,FIRE/S,TIME/N/K,JOYPORT/N/K,UNIT/N/K Examples: RocketTool LEFT TIME 100 RocketTool RIGHT UP 50 FIRE RocketTool FIRE RocketTool JOYPORT 1 Purpose: Very simple shell tool to control a USB Rocket or Missile Launcher available from various sources on the internet. Only weapons of mass destruction with Vendor ID = 0x1130 and Product ID = 0x0202 are supported. Note that the devices will mistakenly report as HID device, but they don't actually speak HID conformant commands (which is a pity). On the first launch of RocketTool, any HID binding will be removed automatically. Usage: LEFT/S - turn the rocket pad to the left for some time. RIGHT/S - turn the rocket pad to the right for some time. UP/S - change the pitch up. DOWN/S - aim lower. FIRE/S - launch one of the three missiles. TIME/N/K - optionally give the time of the movement in ticks (one tick is 1/50sec). JOYPORT/N/K - instead of giving the direction, connect controls to the joystick or joypad at the given port. Of course, you can also use a USB joypad for this job. To exit, press Ctrl-C. UNIT/N/K - if multiple rocket launchers are connected, you can choose the right unit with this argument. Defaults to unit 0 of course. @endnode @node powmantool "PowManTool" @{b}--------------------------------------------------------------------------- PowManTool ---------------------------------------------------------------------------@{ub} Command : PowManTool 1.0 Template: SOCKET=OUTLET/N,ON/S,OFF/S,TOGGLE/S,STATUS/S,UNIT/N/K Examples: PowManTool 1 ON ; Turns socket 1 on PowManTool 2 OFF ; Turns socket 2 off PowManTool 3 TOGGLE ; Toggles power at socket 3 PowManTool OFF ; Turns all sockets off PowManTool 4 STATUS ; Returns WARN if socket 4 is not powered. PowManTool OFF STATUS ; Returns WARN if any socket is powered Purpose: Very simple shell tool to control GemBird SIS-PM Silvershield PowerManager sockets/outlets. Only devices with Vendor ID = 0x04b4 and Product ID = 0xfd11 are supported. Note that the devices will mistakenly report as HID device, but they don't actually speak HID conformant commands (which is a pity). On the first launch of PowManTool, any HID binding will be removed automatically. Usage: SOCKET=OUTLET/N - number of the socket to change. If not given, command applies to all four sockets. ON/S - enable power on the given socket(s), or when used with STATUS/S, return OK when socket is powered, WARN otherwise. OFF/S - disable power on the given socket(s), or when used with STATUS/S, return WARN when socket is powered, OK otherwise. TOGGLE/S - switches power off, if it was powered before, or on, if it wasn't. When used with STATUS/S, it will first toggle the socket(s), and then check, if it or they are now on (see ON/S). STATUS/S - checks the status of one or more sockets. Normally returns WARN, if one or more sockets are turned off. OFF/S inverts this check. UNIT/N/K - if multiple power managers are connected, you can choose the right unit with this argument. Defaults to unit 0 of course. @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" - @{" egalaxtouch.class " link egalaxtouch.class} for Touchscreens by EGalax - @{" simplemidi.class " link simplemidi.class} for MIDI to keyboard conversion - @{" camdusbmidi.class " link camdusbmidi.class} for full MIDI support - @{" usbaudio.class " link usbaudio.class} for USB audio streaming devices - @{" printer.class " link printer.class} for usb printers - @{" massstorage.class " link massstorage.class} for USB mass storage devices (CF-readers, ZIP etc.) - @{" adaptecxchg.class " link adaptecxchg.class} for USB SCSI Adapters by Adaptec - @{" ptp.class " link ptp.class} for PTP (DigiCams) and MTP (MP3-Player) devices - @{" cdcacm.class " link cdcacm.class} for USB modems confirming to the ACM standard - @{" serialpl2303.class " link serialpl2303.class} for Prolific USB->serial adapters - @{" serialcp210x.class " link serialcp210x.class} for CP210x USB->serial adapters - @{" rawwrap.class " link rawwrap.class} to access vendor specific interfaces via usbraw.device - @{" pegasus.class " link pegasus.class} for Pegasus chipset USB->ethernet adapters - @{" asixeth.class " link asixeth.class} for ASIX chipset USB->ethernet adapters - @{" dm9601eth.class " link dm9601eth.class} for Davicom chipset USB->ethernet adapters - @{" moschipeth.class " link moschipeth.class } for MOS chipset USB->ethernet adapters - @{" rtl8150eth.class " link rtl8150eth.class } for RealTek 8150 chipset USB->ethernet adapters - @{" ethwrap.class " link ethwrap.class} for USB data link cables - @{" dfu.class " link dfu.class} for upgrading USB firmware - @{" usbvideo.class " link usbvideo.class} for USB UVC standard webcams with MJPEG 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 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 Binding to: interface, classcode 3 (HID), any subclass, any protocol Config GUI: separately for each interface and default class settings. After months of hard work and over 600 KB of source code, I can present you the third 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} and will be available right after booting, but with some features (such as executing programs) not working at boot time. @{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. Turbo mouse: Requested by bigfoot. Will override the interval to one millisecond regarding the polling time. Some mice will cope with this and return the mouse data at a higher rate, resulting in much smoother operation. This switch is probably only interesting under MorphOS, because it might cause more unnecessary CPU drain. 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. - Analogue Hack: Tells Poseidon to force reporting of analogue data at the port. Please note that this only works with programs that understand the analogue data, because it's an extension to the original lowlevel.library standard made by Commodore. If you want to incorporate this feature in your software, just contact me and I will send you the necessary information. Currently, the game VGP2 and SDL games under MorphOS support analogue data. Rumble Port: As addition to the analogue data, the HID class supports applications and games that want to utilize a rumble pack or force feedback motors in the gamepads. This field selects to which lowlevel port the hid device responds, when attempting to use the rumble pack. Normally, this corresponds to the port that has been set in the actions for the joypad. HID Output Control Window: The new hid.class supports the creation of a GUI window to control HID output features. This can be used for controlling output stuff on the fly (imagine a nuclear power plant with USB plug -- or a coffee cup holder). Of course, you can also use this to control the LEDs of your USB keyboard or to play with the rumble pack of your joypad. If you select "Open on startup", the window will appear as soon as you connect the device. Clicking on "Open now" will cause the window to be opened. For your convenience, the title of the window can be changed into something more appropriate, like "Hamster remote control". The given Rexx Port name will be used for receiving standard MUI commands like SHOW and HIDE, notice that it will be getting a number appended (usually ".1", but also higher ones, if there are duplicates). More ARexx support is planned, but not yet included. Keyboard Settings include (this only applies to the Action Type "Keymapping"): - Two listviews where you can select which key of a 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 is 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. The new hid.class generates internal conversion tables that will show up as "[Wacom Support]" collection to support these silly tablets. - @{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. To quickly change the target port of a joypad, there's a menu item that will fix the port number in the action items of the whole collection you've selected. Saves a lot of time. 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 separate 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. - @{b}Analogue joystick@{ub} The new hid.class supports analogue data via an extension of the lowlevel.library specification. Details on how to add support for this in your own application are available on request. Currently, only two axis are supported at a resolution of 8 bit each. No calibration is done so far, so the application has to take care of the value not being centered or full range. Fire buttons are set up in the digital joystick action (they are digital after all). The extension allows games to automatically detect and switch to analogue data, if available. You can force a port to report *only* analogue data using the "Analogue Hack" option in the "Global Settings", but this will cause older software expecting digital data to go bonkers. - @{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 a 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! - Flush events: This is only necessary to synchronize output or feature items writing. Using this action item will flush any pending (modified) output or feature item changes to the device, making it possible to write whole sequences to the device. Internally, this is generated for AipTek and Wacom tablets startup sequences. - @{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 (and in fact, this is now done by default for tablets). - 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 a 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 separate 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 Binding to: interface, classcode 3 (HID), subclass 1, protocol 2 only. Config GUI: separately 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 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 egalaxtouch.class "The EGalaxTouch Class Driver" @{b}--------------------------------------------------------------------------- egalaxtouch.class ---------------------------------------------------------------------------@{ub} Class: egalaxtouch.class Binding to: device, vendor/product: 0x0123/0x0001, 0x0123/0x0002 0x0EEF/0x0001, 0x0EEF/0x0002 0x3823/0x0001, 0x3823/0x0002 Config GUI: separately for each device and default class settings. This is a special (paid order) class driver for Touchscreens from EGalax. It converts finger tips on the screen into mouse movements and presses with the left mouse button. Right mouse button is emulated by pressing and holding your finger tip on the screen -- there are several different options on this handling the prefs. The prefs here are for calibration the touching point and dimensions. After chosing the right orientation of your touch screen with the mirror and rotate options, click on "Track dimensions" and move your finger along the outer boundaries of the touch screen. After that, disable the "Track dimensions" settings again. @endnode @node simplemidi.class "The SimpleMIDI Class Driver" @{b}--------------------------------------------------------------------------- simplemidi.class ---------------------------------------------------------------------------@{ub} Class: simplemidi.class Binding to: interface, classcode 1 (Audio), subclass 3 (Midi), any protocol Config GUI: global class prefs This class driver connects to MIDI keyboards and interpretes and converts the incoming presses into keyboard presses, using a conversion table as used in most Tracker-based applications such as ProTracker, NewTracker, OctaMed, and so on. While this is no replacement for a real CAMD midi driver, this is a good immediate solution. In the meanwhile, there is also a real CAMD midi driver (camdusbmidi.class). The mapping of the midi keyboard to the keys looks like this (american keymap): | | s| d| | | g| h | j| | | 2| 3| | | 5| 6 | 7| | | 9| 0| | | | |__|__| | |__|___|__| | |__|__| | |__|___|__| | |__|__| | | | z | x | c | v | b | n | m | q | w | e | r | t | y | u | i | o | p | [ | |___|___|___|___|___|___|___|___|___|___|___|___|___|___|___|___|___|___| C#1 D#1 F#1 G#1 A#1 C#2 D#2 F#2 G#2 A#2 C#3 D#3 E#3 C-1 D-1 E-1 F-1 G-1 A-1 B-1 C-2 D-2 E-2 F-2 G-2 A-2 B-2 C-3 D-3 E-3 F-3 When switching to higher octaves, the function keys will be pressed accordingly (F1 to F9). Using the GUI you can determine the starting octave of your keyboard and how many octaves you want to support (using the function keys). If you don't want to have any sustain, enable the "Automatic KeyUp Event" switch in the GUI. @endnode @node camdusbmidi.class "The CAMD USB MIDI Class Driver" @{b}--------------------------------------------------------------------------- camdusbmidi.class ---------------------------------------------------------------------------@{ub} Class: camdusbmidi.class Binding to: interface, classcode 1 (Audio), subclass 3 (Midi), any protocol Config GUI: not yet (global class prefs and individual device prefs) Unlike the @{" simplemidi.class " link simplemidi.class} which converts MIDI IN data into keystrokes, the camdusbmidi.class is a real camd.library driver, acting as an adapter between the serial MIDI protocol and the USB MIDI Interface. On the first connection of the MIDI Interface, a CAMD driver will be saved into the "DEVS:Midi" directory (the directory will be created, if non-existant), named after the device connected (abbreviated by illegal characters such as spaces). This is necessary due to the braindead CAMD driver architecture, and some OS4 people (e.g. Davy Wenzler) violating the AROS Public Licence by not releasing the modified camd.library source code (this is due several months, so don't tell me you forgot about it). The driver supports both the original Commodore camd.library V37 and the AROS/AmigaOS/MorphOS replacement library, versioned V40. Depending on which library is installed, you might need to configure the camd.library to use the USB driver using the MIDI Prefs (I had problems changing the MIDI Prefs, if there was a config file already, so you could try to delete the ENVARC:sys/midi.prefs, if you have this problem, too). By default the driver offers 16 ports (this will probably change in future to support the actual amount of "virtual cables" offered). SysEx messages are fully supported. The driver is in beta status. I've tested it with my USB MIDI keyboard (without tone generator, so this is a MIDI IN (from the host side view) only keyboard) and both CAMD versions, together with PlayMF, SoftSynth, PianoMeter and several other CAMD Tools. Moreover, I've tried to use it with Bars'n Pipes (AmigaOS 68k), but I wasn't really able to make sense of the controls to get something out of the keyboard. MIDI OUT should work (I've seen the messages go out), but I couldn't test this with my keyboard. Testers are welcome. There is no configuration GUI yet -- it might be added later. @endnode @node usbaudio.class "The USB Audio Class Driver" @{b}--------------------------------------------------------------------------- usbaudio.class ---------------------------------------------------------------------------@{ub} Class: usbaudio.class Binding to: interface, classcode 1 (Audio), subclass 2, any protocol Config GUI: not yet (global class prefs and individual device prefs) This class supports USB Audio devices such as USB sound cards. It requires the USB realtime isochronous extension. When connected, the class will automatically add USB AHI modes to the list of available audio modes. At least AHI V6.x is required. Some USB sound cards are limited in their output capabilities and will only support on or two playback or sampling rates. If you get distortions, try a different mode. USB audio requires some CPU power and playback of MP3s through USB audio requires at least an 68060, but a PPC is usually better. Don't unplug the USB device while playing. That's evil. There is no configuration GUI yet -- it might be added later. @endnode @node printer.class "The Printer Class Driver" @{b}--------------------------------------------------------------------------- printer.class ---------------------------------------------------------------------------@{ub} Class: printer.class 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 a 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 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: Separately 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 not suitable 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 USB2.0 this is much better. On the first connection of such an MSD, an "usbscsi.device" unit 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 existing; 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 mountlist anymore. V3.4 added mounting of CD/DVD drives. Starting with version 1.13, these mounting features can be disabled in the configuration GUI. V3.0 also allows the automatic unmounting of partitions (use with care, some filesystems might have trouble with that!). Also, the default name for FAT and CD partitions can be changed, along with the buffer settings. This GUI also holds fields for the filesystem to use for FAT and NTFS partitions. There is a field to set the "Control" string e.g. for disabling the generation of file comments. New in V3.0 is the possibility to change the MaxTransferRate and also to probe for the maximum. 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). Note that mechanical devices such 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. Normally, automatic fallbacks are active that will detect error situations and turn on the switches accordingly. - Single LUN: Only use LUN 0, even if the device has more than one. Some devices barf at the GET_MAX_LUN command and die. - Simple SCSI: Filter out or emulate most SCSI commands that are not used by Windows and hence, a lot of devices will drop dead on these (or just return junk). It will also intercept all calls to MODE_SENSE and returns faked but accurate geometry data. - Trim Inquiry: A lot of devices are scared to death by Inquiry commands with more than 36 byte buffers (although some even propose they have more data available). This switch trims the request to 36 bytes. - Fake Inquiry: Filter the Inquiry command and replace it by an internal faking routine. This is last resort. Inquiry should always work, at least with Trim Inquiry enabled. If you use this on CD/DVD drives, CD software may be confused. - Fix Capacity: There is a SCSI command called GET_CAPACITY which returns the size of a physical sector and the indirectly the size of the device by returning the number of the very last sector of the medium. Now a lot of devices return the total number of sectors here, but as the counting of sectors starts at 0, this is wrong by one. Hence, the device will appear one sector too large, which is a problem. Fix Capacity will reduce the GET_CAPACITY by one to compensate. The mass storage class will also warn you if it thinks you'd rather should turn this switch on or off, but it cannot know for sure (except for probing the last sector, which probably will cause all kind of havoc to the already broken firmware). - No Initial Reset: Disables BULK_RESET sending before the first command. If you encounter bulk reset error messages, try this. A few devices need this OFF however. - Translate CMD6->CMD10: Changes some SCSI commands to their 10 bytes counterparts. Most broken firmwares cannot handle the 6 byte versions, though they are standard. - Better Removable Support: Enable this, if your USB device has a good firmware and supports write protection etc. Doesn't work with Simple SCSI enabled. - Ignore broken CSS-ID: USB defines wrappers for Commands (CBW) and Status (CSS) packets. Each have specific ID. Unfortunately, some devices managed to use a wrong CSS-ID. Enable this switch if you get error messages on the Command Status. The class usually already knows of a few broken devices. - Emulate on larger block sizes: More and more devices are emerging with physical block sizes larger than 512 bytes (e.g. 2 KB blocks). While this is no problem for the FFS or SFS filesystems, some legacy software and FAT95 have the problem that they want to access the disk in 512 byte blocks -- which then fail on the devices with larger blocks. Using this switch access to unaligned blocks or shorter data length are emulated (slightly slower though). - 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 ptp.class "The Picture Transfer Protocol Class Driver" @{b}--------------------------------------------------------------------------- ptp.class ---------------------------------------------------------------------------@{ub} Class: ptp.class Binding to: interface, classcode 6 (still image), subclass 1, protocol 1 optionally: interface, MTP specific device detection Config GUI: Separately for each interface, default class settings This is a standard class driver for digital cameras using the Picture Transfer Protocol (PTP) or sometimes also called PictBridge. It also can be used for MP3-Players using the proprietary Media (Microsoft?) Transport Protocol MTP, which has not been yet adopted to the official USB standards and hence uses a vendor specific class code and detection system (which sucks). Unlike mass storage devices, PTP devices provide a hierarchical filesystem view upon the device and hence do not need partitioning for physical media and a underlying filesystem driver. However, the PTP specification lacks at several points. Usually, you're better off, if you can switch your device to mass storage mode or use a card reader. The ptp.class provides a DOS device and volume via its integrated DOS handler once a PTP device is connected. The DOS device name can be set in the configuration and defaults to "PTP:", the volume name is created accordingly to the camera name. The PTP specification supports several "storages" which will be listed in the root directory (MS Windows only supports the very first storage). In most cases, you will only be able to read files from the device. PTP supports two commands called GetObject and GetPartialObject. If a PTP device does not support GetPartialObject, the whole file needs to be fetched from the device, even if only 1 byte will be read. In this case, the ptp.class will cache the last opened file in memory for faster access. You can force devices to use GetObject instead of GetPartialObject on operations reading more than 32 KB, if you want to. There's a switch in the GUI for this. This makes copying operations a bit faster, because programs only requesting small blocks will cause a significant overhead. Write operations are not supported by most devices and are a bit fragile, because the file will be generated in memory first and only the attempt to write to the device will be made when it is closed by the application. If the sending of the file to the camera or MTP MP3 player fails, the application will not know or show this! Renaming of files is not possible -- merely moving files from one directory to another might be supported. PTP only supports a simple protection scheme, allowing files to be made read-only -- if the device supports this command. Comments are provided via the keywords field and are read-only. PTP supports two date stamps per file (creation and modification) -- for AmigaDOS only the modification date is returned. Deletion of files may be possible, if the device supports it. Deletion may also be attempted on directories and may even work there. However, PTP does not specify the creation of directories and hence this is not supported. WARNING: If you disconnect the camera or MP3 player while there are pending locks or filehandles, Poseidon will hang until you release these locks (PsdErrorlog will tell you which files are still locked). The configuration GUI allows the change of the default DOS name of the device. For the class configuration, enabling and disabling MTP detection is possible. By default MTP detection is disabled because some vendor specific non-MTP devices crash on the detection attempt. You still can use forced interface bindings for MTP devices even with MTP detection disabled. The ptp.class can be installed as a @{" RomTag " link romtags}, but will not start itself before dos.library is available. @endnode @node cdcacm.class "The Communcation Device Class Driver for Abstract Control Model" @{b}--------------------------------------------------------------------------- cdcacm.class ---------------------------------------------------------------------------@{ub} Class: cdcacm.class 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 (or mobile phones connected via USB). 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 class has been heavily reworked for Poseidon V3.0. 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 Binding to: device, vendor/product: 0x067b/0x2303, 0x067b/0x04bb ProLific 0x0557/0x2008, 0x0547/0x2008 ATen 0x04bb/0x0a03 IOData 0x056e/0x5003 ElCom 0x0eba/0x1080 Itegno 0x0df7/0x0620 MA620 0x0584/0xb000 Ratoc 0x2478/0x2008 Tripp 0x1453/0x4026 Radioshack 0x0731/0x0528 DCU10 0x6189/0x2068 Sitecom 0x11f7/0x02df Alcatel 0x04e8/0x8001 Samsung Config GUI: none This is a class driver for a some USB->serial adapters manufactured by the vendors listed above. 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 class has been heavily reworked for Poseidon V3.0. The serialpl2303.class can be installed as a @{" RomTag " link romtags}, though this is not very useful except for debugging purposes. @endnode @node serialcp210x.class "The Serial CP210x Class Driver" @{b}--------------------------------------------------------------------------- serialcp210x.class ---------------------------------------------------------------------------@{ub} Class: serialcp210x.class Binding to: device, vendor/product: 0x0FCF/0x1003 Dynastream ANT 0x10A6/0xAA26 Knock-off DCU-11 cable 0x10AB/0x10C5 Siemens MC60 Cable 0x10B5/0xAC70 Nokia CA-42 USB 0x10C4/0x803B Pololu USB-serial 0x10C4/0x807A Crumb128 board 0x10C4/0x80CA Degree Controls Inc 0x10C4/0x80F6 Suunto sports instrument 0x10C4/0x813D Burnside Telecom 0x10C4/0x815E Helicomm IP-Link 1220-DVM 0x10C4/0xEA60 Silicon Labs factory def. 0x16D6/0x0001 Jablotron serial Config GUI: none This is a class driver for a some USB->serial adapters manufactured by the vendors listed above. 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 "serialcp210x.device" which is created during runtime. The serialcp210x.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 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 dfu.class "The Device Firmware Upgrade Class Driver" @{b}--------------------------------------------------------------------------- dfu.class ---------------------------------------------------------------------------@{ub} Class: dfu.class Binding to: interface, classcode 254 (DFU), any subclass, any protocol Config GUI: individual interface control window This class will bind to a Device Firmware Upgrade Interface, usually found on Bluetooth sticks and other devices with, well, upgradable firmware. The class driver allows downloading (from USB device to host) of the current firmware (not all devices seem to support this) and uploading (from host to USB device) firmware. While downloading is an uncritical process, @{b}upgrading the firmware is dangerous and can potentially destroy the device@{ub}. Do not unplug the device during upload, do not reset the machine or turn the power off! If the upgrading failed, some devices will reattach in DFU mode and allow the recovery by a successful uploading process, others even might refuse doing this. I already have killed one Bluetooth stick, so be warned. To use this class, you simply have to open the configuration GUI of the device for the DFU interface. There is a button labeled "Enter DFU Mode" to change the operational mode of the device into the special firmware upgrading (DFU) mode. This is necessary because during normal operation, the device cannot be upgraded. After switching the device into DFU mode, it will disconnect and reconnect automatically and the GUI should come up again automatically with optional downloading and upgrading buttons and a field for selecting the target or source file. Firmware files can be obtained from the internet and normally have the extension ".dfu". Do not attempt to write a non-firmware file into the device, or a firmware for a different chipset. The device should check this during upload, but you never know... Before upgrading the firmware, you should try to download the old one, in case you want to revert to the old version. Keep the file in a safe place. Again, be careful with this class, it could easily happen that you render your expensive USB device useless. Use at your own risk. @endnode @node pegasus.class "The Pegasus Class Driver" @{b}--------------------------------------------------------------------------- pegasus.class ---------------------------------------------------------------------------@{ub} Class: pegasus.class Binding to: device, about 70 different USB ethernet adapters Config GUI: separately for each device and default class settings. This is a class driver for a whole series of USB->Ethernet adapters manufactured by Melco, Belkin, SMC, ADKtek, LinkSys, IO-Data, Billionton, Netgear, D-Link, LANEED and various others, that use the Pegasus or Pegasus II chipset. These adapters can be used to connect standard TP Ethernet LAN cables with 10MBit/s or 100MBit/s to your computer. Please note that though the adapter advertises itself as 100MBit/s, you'll only be able to get close to 10MBit/s with USB1.1. To the AmigaOS the USB device is available through the "usbpegasus.device" SANA-II device which is created in memory during runtime. Hence you will not be able to find a file based device in DEVS:Networks as usually expected. By default the class with do auto-negotiation at binding time, or fall back to 100MBit/s Full Duplex, if no cable is connected. The device does not poll for later cable connection in auto-negotiation mode, thus you probably need to go offline/online with your TCP/IP stack, if your setup is not 100MBit Full Duplex. You can override the Media Type setting within the GUI. Most adapters come with a valid MAC address -- some might not. In any case you can override the default MAC address in the GUI. Additionally you can change the default unit number of the usbpegasus.device, if you wish. Note that the "Home PNA" (LAN via phone line, popular in the US) feature of some adapters is not supported. The pegasus.class can be installed as a @{" RomTag " link romtags}, though this is not very useful except for debugging purposes. @endnode @node asixeth.class "The AsixEth Class Driver" @{b}--------------------------------------------------------------------------- asixeth.class ---------------------------------------------------------------------------@{ub} Class: asixeth.class Binding to: device, about 21 different USB ethernet adapters Config GUI: separately for each device and default class settings. This is a class driver for a whole series of USB->Ethernet adapters manufactured by Asix, Aten, Billionton Systems, Buffalo, Corega, DLink, Goodway, Hawking, Intellinet, IO-Data, JVC, LinkSys, NetGear, Sitecom and Surecom and various others, that use the Asix AX88172, AX88178 or AX88772 chipset. These adapters can be used to connect standard TP Ethernet LAN cables with 10MBit/s, 100MBit/s or even 1000MBit/s to your computer (but don't get the wrong idea, you probably won't be able to take advantage of 100MBit/s over USB 1.1, and even on USB 2.0 cards, the TCP/IP stack usually is the bottleneck on 68k systems). To the AmigaOS the USB device is available through the "usbasixeth.device" SANA-II device which is created in memory during runtime. Hence you will not be able to find a file based device in DEVS:Networks as usually expected. By default the class with do auto-negotiation at binding time, or fall back to 100MBit/s Full Duplex, if no cable is connected. The device does not poll for later cable connection in auto-negotiation mode, thus you probably need to go offline/online with your TCP/IP stack, if your setup is not 100MBit Full Duplex. You can override the Media Type setting within the GUI. The adapters come with valid MAC address. Overriding the MAC address in the GUI might not work as expected. Additionally you can change the default unit number of the usbasixeth.device, if you wish. The asixeth.class can be installed as a @{" RomTag " link romtags}, though this is not very useful except for debugging purposes. @endnode @node dm9601eth.class "The DM9601Eth Class Driver" @{b}--------------------------------------------------------------------------- dm9601eth.class ---------------------------------------------------------------------------@{ub} Class: dm9601eth.class Binding to: device, about 6 different USB ethernet adapters Config GUI: separately for each device and default class settings. This is a class driver for a whole series of USB->Ethernet adapters manufactured by Davicom, Corega, ShanTou, ADMtek, Hirose and various others, that use the Davicom DM9601 chipset. These adapters can be used to connect standard TP Ethernet LAN cables with 10MBit/s or 100MBit/s to your computer (but don't get the wrong idea, you probably won't be able to take advantage of 100MBit/s over USB 1.1, and even on USB 2.0 cards, the TCP/IP stack usually is the bottleneck on 68k systems). To the AmigaOS the USB device is available through the "dm9601eth.device" SANA-II device which is created in memory during runtime. Hence you will not be able to find a file based device in DEVS:Networks as usually expected. By default the class with do auto-negotiation at binding time, or fall back to 100MBit/s Full Duplex, if no cable is connected. The device does not poll for later cable connection in auto-negotiation mode, thus you probably need to go offline/online with your TCP/IP stack, if your setup is not 100MBit Full Duplex. You can override the Media Type setting within the GUI. The adapters come with valid MAC address. Overriding the MAC address in the GUI might not work as expected. Additionally you can change the default unit number of the dm9601eth.device, if you wish. The dm9601eth.class can be installed as a @{" RomTag " link romtags}, though this is not very useful except for debugging purposes. @endnode @node moschipeth.class "The MosChipEth Class Driver" @{b}--------------------------------------------------------------------------- moschipeth.class ---------------------------------------------------------------------------@{ub} Class: moschipeth.class Binding to: device, different USB ethernet adapters Config GUI: separately for each device and default class settings. This is a class driver for a whole series of USB->Ethernet adapters manufactured by MosChip Semiconductors (MCS7830 chipset). These adapters can be used to connect standard TP Ethernet LAN cables with 10MBit/s or 100MBit/s to your computer (but don't get the wrong idea, you probably won't be able to take advantage of 100MBit/s over USB 1.1, and even on USB 2.0 cards, the TCP/IP stack usually is the bottleneck on 68k systems). To the AmigaOS the USB device is available through the "moschipeth.device" SANA-II device which is created in memory during runtime. Hence you will not be able to find a file based device in DEVS:Networks as usually expected. By default the class with do auto-negotiation at binding time, or fall back to 100MBit/s Full Duplex, if no cable is connected. The device does not poll for later cable connection in auto-negotiation mode, thus you probably need to go offline/online with your TCP/IP stack, if your setup is not 100MBit Full Duplex. You can override the Media Type setting within the GUI. The adapters come with valid MAC address. Overriding the MAC address in the GUI might not work as expected. Additionally you can change the default unit number of the moschipeth.device, if you wish. The moschipeth.class can be installed as a @{" RomTag " link romtags}, though this is not very useful except for debugging purposes. @endnode @node rtl8150eth.class "The RTL8150Eth Class Driver" @{b}--------------------------------------------------------------------------- rtl8150eth.class ---------------------------------------------------------------------------@{ub} Class: rtl8150eth.class Binding to: device, different USB ethernet adapters Config GUI: separately for each device and default class settings. This is a class driver for a whole series of USB->Ethernet adapters manufactured by RealTek (RTL8150 chipset). These adapters can be used to connect standard TP Ethernet LAN cables with 10MBit/s or 100MBit/s to your computer (but don't get the wrong idea, you probably won't be able to take advantage of 100MBit/s over USB 1.1, and even on USB 2.0 cards, the TCP/IP stack usually is the bottleneck on 68k systems). To the AmigaOS the USB device is available through the "rtl8150eth.device" SANA-II device which is created in memory during runtime. Hence you will not be able to find a file based device in DEVS:Networks as usually expected. By default the class with do auto-negotiation at binding time, or fall back to 100MBit/s Full Duplex, if no cable is connected. The device does not poll for later cable connection in auto-negotiation mode, thus you probably need to go offline/online with your TCP/IP stack, if your setup is not 100MBit Full Duplex. You can override the Media Type setting within the GUI. The adapters come with valid MAC address. Overriding the MAC address in the GUI might not work as expected. Additionally you can change the default unit number of the moschipeth.device, if you wish. The rtl8150eth.device can be installed as a @{" RomTag " link romtags}, though this is not very useful except for debugging purposes. @endnode @node ethwrap.class "The EthWrap Class Driver" @{b}--------------------------------------------------------------------------- ethwrap.class ---------------------------------------------------------------------------@{ub} Class: ethwrap.class Binding to: device, about ten different USB data link adapters Config GUI: separately for each device and default class settings. This is a class driver for a whole series of USB data link adapters. These adapters can be used to link two computers together, just like a serial null modem cable. However, the data transfer is not a serial link, but rather uses Ethernet packets. Please note that you need to connect both ends of the link cable before using the adapter. There is no flow control, which means that if the other end is not ready to receive, the class will hang until NAK timeout. The class was tested between an Amiga and a Linux box, but it should also work between Amiga and Windows systems. To the AmigaOS the USB device is available through the "usbethwrap.device" SANA-II device which is created in memory during runtime. Hence you will not be able to find a file based device in DEVS:Networks as usually expected. As these adapters do not come with a valid MAC address, the class will generate one randomly at configuration generation time (so after saving your prefs, this MAC will stay the same). In any case you can override this randomly generated MAC Address in the GUI. Additionally you can change the default unit number of the usbethwrap.device, if you wish. The ethwrap.class can be installed as a @{" RomTag " link romtags}, though this is not very useful except for debugging purposes. @endnode @node usbvideo.class "The USB Video Class Driver" @{b}--------------------------------------------------------------------------- usbvideo.class ---------------------------------------------------------------------------@{ub} Class: usbvideo.class Binding to: interface, classcode 14 (Video), subclass 1, MJPEG only Config GUI: not yet This class creates VHI Studio driver for USB webcams that conform to the USB Video Class (UVC) standard. It allows to take snapshots of the images from USB webcams that support motion JPEG (MJPEG) format. Currently, no other output formats are supported. Warning: usbvideo.class only works with host controllers that support realtime iso transfers. 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 have the possibility to take snapshots. The speed of the recording depends on your machine and camera. @endnode @node adaptecxchg.class "The Adaptec X-Change Class Driver" @{b}--------------------------------------------------------------------------- adaptecxchg.class ---------------------------------------------------------------------------@{ub} Class: adaptecxchg.class Binding to: device, vendor/product: 0x03F3/0x2000 Adaptec USB Xchange Config GUI: none This class is simply a small firmware loader that will upload the adaptec firmware image into the device. After the firmware uploading, the USB SCSI adapter will disconnect and reappear as standard USB Mass Storage device. @endnode @node hardwaredrivers "Included hardware drivers" @{b}--------------------------------------------------------------------------- Hardware Drivers ---------------------------------------------------------------------------@{ub} The Poseidon package includes hardware drivers for the Rapid Road USB card. Other drivers delivered with older releases of Poseidon will still work, same for third party drivers. 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 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: My USB Mass storage device is mounted, but comes up as "Not a DOS disk"? A: Reformat it on a PC and try again. FAT95 is sometimes more strict on the file format and easily rejects media not 100% conforming. Q: I cannot find the usbparallel.device, usbasixeth.device, usbscsi.device etc. anywhere. Where are they? A: They are generated in memory as soon as the corresponding class is loaded. Q: But I need to select the device in some programs using a file requester! What can I do? A: As in-memory devices and libraries are found before the operating system looks for it on disc, you can create a dummy file (e.g. an empty one with "Echo NOLINE >DEVS:Networks/usbasixeth.device") which can be selected with the file requester, but serves no other purpose, because the in-memory device is going to be opened first. Q: It doesn't work. What can I do? A: Provide me with all information you can get. Use the online reporting tool in Trident. Don't send screenshots. "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 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. Email: chrisly(!)platon42.de WWW: http://www.platon42.de/ Wishlist: http://www.amazon.de/gp/registry/wishlist/1123KBN787GJQ @endnode