NAME

Win32::FTDI::FTD2XX - PERL5 interface to FTDI's D2XX Direct USB Drivers

SYNOPSIS


            
              
              use Win32::FTDI::FTD2XX qw(:DEFAULT
      FT_BAUD_38400 FT_BITS_8 FT_STOP_BITS_1 FT_PARITY_NONE
      FT_FLOW_RTS_CTS PFT_MODEM_STATUS_CTS
      );
my $FTD = Win32::FTDI::FTD2XX->new();
unless( $FTD->PFT_STATUS() == FT_OK )
  {
  printf( STDERR "FTD2XX::new() failed: %s (%s)\n", 
          $FTD->PFT_STATUS_MSG(), $FTD->PFT_ERROR() );
  exit( 1 );
  } 
printf( "FTD2XX::new() allocated PFT_HANDLE: %d\n", $FTD->PFT_HANDLE() );
my $numDevices = $FTD->GetNumDevices();
unless( $FTD->PFT_STATUS() == FT_OK )
  {
  printf( STDERR "FTD2XX::GetNumDevices() failed: %s (%s)\n",  
          $FTD->PFT_STATUS_MSG(), $FTD->PFT_ERROR() );
  exit( 1 );
  } 
printf( "Found $numDevices FTDI devices connected!\n" );

DESCRIPTION

Win32::FTDI::FTD2XX provides a Perl5 interface to FTDI's D2XX Direct USB Drivers (CDM 2.04.06 as of this writing). It comes in two major components, the FTD2XX.pm module and an encapsulation and abstraction library, called P5FTD2XX.DLL, which wraps the FTDI FTD2XX.DLL, providing a cleaner interface which works better with Win32::API.

For instance, the simpler parameter passing mechanisms of Win32::API were never meant to handle things like (de)referencing and passing of pointers to pointers to buffers etc. The native FT_Open() driver function requires this to open the device handle, which then becomes the primary identifier for the connection to the rest of the API routines. Even when trying to pass the returned pointer around as an opaque datatype when returned through Win32::API, it fails to be recognized as a valid handle by the FT library, since the underlying pointer type's value/meaning gets mangled.

The P5FTD2XX Windows DLL abstracts the more complicated API calls and datatypes (like wrapping 'FT_HANDLE' with 'PFT_HANDLE') and provides other extensions to allow Perl to more conveniently interact with the FTDI devices using the native CDM drivers instead of the Virtual Comm Port (VCP), which can be problematic on Windows when trying to use older interfaces like Win32::CommPort or Win32::Serial.

The Win32::FTDI Perl object further abstracts and extends the API to make it most convenient for the Perl programming space, and looks after allocating & deallocating the PFT_HANDLEs and packed datatypes for parameter passing. In general, any export (see EXPORTS below) beginning with 'FT' is a direct Perl derivative of the original typedef's and #define's from the FTD2XX.H file. Any export prefixed with 'PFT' is an extension provided by the Win32::FTDI::FTD2Xxx.pm/P5FTD2XX DLL package.

Many of the native FT API's have been completely preserved, such as '(P)FT_SetDataCharacteristics', others, like the multi-function 'FT_Open', have been divided into simpler dedicated interfaces as 'PFT_OpenBySerial' and 'PFT_OpenByIndex' (Note: The object interface methods do not require the 'PFT_' prefix, except where noted). Other convenience methods have been added, like 'waitForModem( bitmask )' and the 'crack...' methods which extract bit fields from FT status bytes for you if you don't care to use the values directly.

Note: For performance gains at load time, each object method is autosplit/ autoloaded on demand, at which time each API Method also imports the actual API function from the DLL.

The entire package was developed and tested using an FTDI UM232R USB to Serial Bridge device, with an Atmel ATmegaX8 AVR microcontroller backend.

EXPORTS

The FT_OK status constant is the only default export, as it is the basis for testing even the object's new() call. The other symbol exports may be chosen as desired on the 'use Win32::FTDI::FTD2XX' line as shown in the synopsis. See the FTD2XX.H header file and the FTD2XX Programmer's Guide for more information on their values. The PFT specific symbols are explained in the METHODS section.

The full list of available exports is: FT_OK FT_INVALID_HANDLE FT_DEVICE_NOT_FOUND FT_DEVICE_NOT_OPENED FT_IO_ERROR FT_INSUFFICIENT_RESOURCES FT_INVALID_PARAMETER FT_INVALID_BAUD_RATE FT_DEVICE_NOT_OPENED_FOR_ERASE FT_DEVICE_NOT_OPENED_FOR_WRITE FT_FAILED_TO_WRITE_DEVICE FT_EEPROM_READ_FAILED FT_EEPROM_WRITE_FAILED FT_EEPROM_ERASE_FAILED FT_EEPROM_NOT_PRESENT FT_EEPROM_NOT_PROGRAMMED FT_INVALID_ARGS FT_NOT_SUPPORTED FT_OTHER_ERROR FT_DEVICE_LIST_NOT_READY PFTE_INVALID_API PFTE_MAX_HANDLES PFTE_INVALID_HANDLE PFTE_WAIT_TIMEOUT FT_BAUD_300 FT_BAUD_600 FT_BAUD_1200 FT_BAUD_2400 FT_BAUD_4800 FT_BAUD_9600 FT_BAUD_14400 FT_BAUD_19200 FT_BAUD_38400 FT_BAUD_57600 FT_BAUD_115200 FT_BAUD_230400 FT_BAUD_460800 FT_BAUD_921600 FT_BITS_8 FT_BITS_7 FT_BITS_6 FT_BITS_5 FT_STOP_BITS_1 FT_STOP_BITS_1_5 FT_STOP_BITS_2 FT_PARITY_NONE FT_PARITY_ODD FT_PARITY_EVEN FT_PARITY_MARK FT_PARITY_SPACE FT_FLOW_NONE FT_FLOW_RTS_CTS FT_FLOW_DTR_DSR FT_FLOW_XON_XOFF FT_PURGE_RX FT_PURGE_TX FT_DEFAULT_RX_TIMEOUT FT_DEFAULT_TX_TIMEOUT FT_DEVICE_BM FT_DEVICE_AM FT_DEVICE_100AX FT_DEVICE_UNKNOWN FT_DEVICE_2232C FT_DEVICE_232R PFT_FLOW_XonChar PFT_FLOW_XoffChar PFT_MODEM_STATUS_CTS PFT_MODEM_STATUS_DSR PFT_MODEM_STATUS_RI PFT_MODEM_STATUS_DCD PFT_BITMODE_RESET PFT_BITMODE_ASYNCBB PFT_BITMODE_MPSSE PFT_BITMODE_SYNCBB PFT_BITMODE_MHBEM PFT_BITMODE_FOISM PFT_BITMODE_CBUSBB PFT_MAX_SERIAL PFT_MAX_DESCR PFT_MAX_HANDLES

OBJECT METHODS

The following methods have been provided for interaction with the P5FTD2XX and FTD2XX libraries. All methods set an internal status of type PFT_STATUS, which will include the values given in the standard FT_STATUS set (i.e. $FT_OK etc), as well as PFT specific values, (i.e. PFTE_INVALID_HANDLE). In some cases, if the method doesn't return some other specific value(s), it will generally return TRUE or FALSE (or undef) to indicate failure. Note: TRUE and FALSE are loosely bound to 1 and 0 respectively. On failure, the PFT_STATUS() accessor method can be used to query the PFT/FT_STATUS error value. PFT_ERROR_MSG() provides a quick string based translation of the error.

Standard parameter conventions apply: {required}, [optional], ...

In most cases, all numeric parameters are automatically packed and unpacked between their scalar and binary equivalents for passing into and out of the APIs. Only specific cases require the application to pack or unpack some datatypes, and will be covered in those methods.

New


            
              
              Parameters: [PFT_DEBUG => {FALSE|TRUE}]
Returns: Object Reference (use PFT_STATUS method to check for errors)
Purpose: Extension Method - Instanciates the FTDI perl object, loads the P5FTD2XX DLL
and (as a dependency) the FTD2XX DLL. It will immediately import the PFT_New() and 
PFT_Free() API's as a bare minimum, allocating a PFT_HANDLE type, which is this object
instance's identifier to the P5FTD2XX library for its lifespan. PFT_HANDLE is synonymous
with FT_HANDLE, and provides one per object instance. You may allocate a maximum of 
PFT_MAX_HANDLES objects. 
The object includes an auto DESTROY method that will close any open FTDI device handle
and deallocate the PFT_HANDLE in the P5FTD2XX interface, when it gets garbage collected
by Perl.
For a description of optional PFT_DEBUG parameter, see the PFT_DEBUG Accessor Method.

GetNumDevices


            
              
              Parameters: None
Return Success: $numDevices 
Return Failure: undef
Purpose: Abstraction Method - Returns the number of connected FTDI devices. 
See FT_ListDevices().

Rescan


            
              
              Parameters: None
Return Success: TRUE
Return Failure: FALSE
Purpose: API Method - See FT_Rescan()
Note: As with other bus controls, there is a wait period of 3-5 seconds after
a USB bus scan where any API call that requires direct connection to the device, 
like GetSerialByIndex() etc, will fail with FT_INVALID_HANDLE until it has 
completely stabilized. The application should account for this wait period, or
setup a polling loop to detect the change in return status.

Reload


            
              
              Parameters: {$devVID, $devPID}
Return Success: TRUE
Return Failure: FALSE
Purpose: API Method - See FT_Reload()

ResetPort


            
              
              Parameters: None
Return Success: TRUE
Return Failure: FALSE
Purpose: API Method - See FT_ResetPort()

ResetDevice


            
              
              Parameters: None
Return Success: TRUE
Return Failure: FALSE
Purpose: API Method - See FT_ResetDevice()

CyclePort


            
              
              Parameters: None
Return Success: TRUE
Return Failure: FALSE
Purpose: API Method - See FT_CyclePort()
Note: As with other bus controls, there is a wait period of 5-8 seconds after
a CyclePort where any API call that requires direct connection to the device, 
like GetSerialByIndex() etc, will fail with FT_INVALID_HANDLE until it has 
completely stabilized. The application should account for this wait period, or
setup a polling loop to detect the change in return status.

GetDriverVersion


            
              
              Parameters: None
Return Success: $driverVersion
Return Failure: undef
Purpose: API Method - See FT_GetDriverVersion()

crackDriverVersion


            
              
              Parameters: [$driverVersion]
Return Success: $driverVersionDotNotation
Return Failure: undef
Purpose: Convenience method - translates the numeric DWORD from the driver to
the equivalent dot notation (ie. "00020405" -> "2.04.05"). 
If $driverVersion is supplied, it should be of the form returned by GetDriverVersion.
If $driverVersion is undefined, GetDriverVersion will be called first to get the value.

GetLibraryVersion


            
              
              Parameters: None
Return Success: $libraryVersion
Return Failure: undef
Purpose: API Method - See FT_GetLibraryVersion()

crackLibraryVersion


            
              
              Parameters: [$libraryVersion]
Return Success: $libraryVersionDotNotation
Return Failure: undef
Purpose: Convenience method - translates the numeric DWORD from the library to
the equivalent dot notation (ie. "00030115" -> "3.01.15"). 
If $libraryVersion is supplied, it should be of the form returned by GetLibraryVersion.
If $libraryVersion is undefined, GetLibraryVersion will be called first to get the value.

GetSerialByIndex


            
              
              Parameters: {$devIndex}
Return Success: $devSerial
Return Failure: undef
Purpose: Abstraction Method - Returns the serial string of the connected FTDI device
at the given index. See FT_ListDevices().

GetDescrByIndex


            
              
              Parameters: {$devIndex}
Return Success: $devDescription
Return Failure: undef
Purpose: Abstraction Method - Returns the description string of the connected FTDI device
at the given index. See FT_ListDevices().

GetDeviceInfo


            
              
              Parameters: {$devIndex}
Return Success: $devInfo
Return Failure: undef
Purpose: Abstraction Method - See FT_GetDeviceInfo(). Returns all the description strings
via a hash reference of the form:
  $devInfo->{TypeID};  # raw numeric device type ID
  $devInfo->{TypeNm};  # translated TypeID name string
  $devInfo->{VID};     # device's VID
  $devInfo->{PID};     # device's PID
  $devInfo->{Serial};  # serial number string
  $devInfo->{Descr};   # description string

OpenBySerial


            
              
              Parameters: {$devSerial}
Return Success: TRUE
Return Failure: FALSE
Purpose: Abstraction Method - Opens a connection to the device based on serial number.
See FT_Open(). Note: The object's Close() method should be called to free any previously
opened FT_HANDLE.

OpenByIndex


            
              
              Parameters: {$devIndex}
Return Success: TRUE
Return Failure: FALSE
Purpose: Abstraction Method - Opens a connection to the device based on index number.
See FT_Open(). Note: The object's Close() method should be called to free any previously
opened FT_HANDLE.

Close


            
              
              Parameters: None
Return Success: TRUE
Return Failure: FALSE
Purpose: API Method - See FT_Close().

SetBaudRate


            
              
              Parameters: {$baudRate}
Return Success: TRUE
Return Failure: FALSE
Purpose: API Method - See FT_SetBaudRate().

SetDivisor


            
              
              Parameters: {$divisor}
Return Success: TRUE
Return Failure: FALSE
Purpose: API Method - See FT_SetDivisor().

SetDataCharacteristics


            
              
              Parameters: {$dataBits, $stopBits, $parityBits}
Return Success: TRUE
Return Failure: FALSE
Purpose: API Method - See FT_SetDataCharacteristics().

SetFlowControl


            
              
              Parameters: {$flowCtrl} [, $XonChar, $XoffChar]
Return Success: TRUE
Return Failure: FALSE
Purpose: API Method - See FT_SetFlowControl(). 
Note: The ANSI standard Xon/Xoff characters have been defined in 
PFT_FLOW_XonChar (0x11), and PFT_FLOW_XoffChar (0x13).

SetTimeouts


            
              
              Parameters: {$readTimeout, $writeTimeout}
Return Success: TRUE
Return Failure: FALSE
Purpose: API Method - See FT_SetTimeouts().

GetTimeouts


            
              
              Parameters: None
Return Success: $readTimeout, $writeTimeout
Return Failure: undef
Purpose: Extension Method - query the current timeout values, as previously set
in SetTimeouts().

SetReadTimeout


            
              
              Parameters: {$readTimeout}
Return Success: TRUE
Return Failure: FALSE
Purpose: Extension Method - Sets the read timeout without disturbing the current
write timeout value.

GetReadTimeout


            
              
              Parameters: None
Return Success: $readTimeout
Return Failure: undef
Purpose: Extension Method - Gets the current read timeout value.

SetWriteTimeout


            
              
              Parameters: {$writeTimeout}
Return Success: TRUE
Return Failure: FALSE
Purpose: Extension Method - Sets the write timeout without disturbing the current
read timeout value.

GetWriteTimeout


            
              
              Parameters: None
Return Success: $writeTimeout
Return Failure: undef
Purpose: Extension Method - Gets the current write timeout value.

SetDtr


            
              
              Parameters: None
Return Success: TRUE
Return Failure: FALSE
Purpose: API Method - See FT_SetDtr().

ClrDtr


            
              
              Parameters: None
Return Success: TRUE
Return Failure: FALSE
Purpose: API Method - See FT_ClrDtr().

SetRts


            
              
              Parameters: None
Return Success: TRUE
Return Failure: FALSE
Purpose: API Method - See FT_SetRts().

ClrRts


            
              
              Parameters: None
Return Success: TRUE
Return Failure: FALSE
Purpose: API Method - See FT_ClrRts().

SetBreakOn


            
              
              Parameters: None
Return Success: TRUE
Return Failure: FALSE
Purpose: API Method - See FT_SetBreakOn().

SetBreakOff


            
              
              Parameters: None
Return Success: TRUE
Return Failure: FALSE
Purpose: API Method - See FT_SetBreakOff().

GetStatus


            
              
              Parameters: None
Return Success: $amountInRxQueue, $amountInTxQueue, $eventStatus
Return Failure: undef
Purpose: API Method - See FT_GetStatus().

GetQueueStatus


            
              
              Parameters: None
Return Success: $amountInRxQueue
Return Failure: undef
Purpose: API Method - See FT_GetQueueStatus().

GetModemStatus


            
              
              Parameters: None
Return Success: $modemStatus
Return Failure: undef
Purpose: API Method - See FT_GetModemStatus().

crackModemStatus


            
              
              Parameters: {$modemStatusBitmask}
Return Success: $statusCTS, $statusDSR, $statusRI, $statusDCD
Return Failure: undef
Purpose: Convenience Method - Based on the provided bitmask, sets each value in the returning
array to TRUE if bit is set, FALSE otherwise. See FT_GetModemStatus().

waitForModem


            
              
              Parameters: {$modemStatusBitmask} [, $timeout] [, $pollTm]
Return Success: TRUE
Return Failure: FALSE (Check PFT_STATUS - FT API failure or PFTE_WAIT_TIMEOUT set)
Purpose: Extension Method - since the event API's are unimplemented, this method may be used
to suspend program execution until one or more of the modem status bits is set (see
GetModemStatus). 
The modemStatusBitmask is formed using the PFT_MODEM_STATUS_xxx bit definitions. i.e.:
  $FTD->waitForModem( PFT_MODEM_STATUS_CTS, 3 );
would wait max 3 seconds for the device's CTS signal to assert itself.
The optional $timeout provides a limiting timeframe to wait, in seconds. Fractional seconds,
i.e. 0.5 (500ms) are allowed. The timeout is infinite if undefined. 
The optional $pollTm is the time in seconds between polls of the device. The default is 0.25
(250ms). 
Note: the timeout is NOT implemented in real time clock fassion, so it should not be used for
critical timing sequences, but is accurate enough for most uses. When setting $timeout and/or
$pollTm, $timeout should be an even multiple of $pollTm, or if not, the overlap in timing should
be accounted for if neccessary.

SetChars


            
              
              Parameters: {$eventCh, $eventChEn, $errorCh, $errorChEn}
Return Success: TRUE
Return Failure: FALSE
Purpose: API Method - See FT_SetChars().
Note: The $eventCh and $errorCh parameters should be specified in numeric form, 
i.e.:  SetChars( 0x12, 1, 0x14, 1 );

SetResetPipeRetryCount


            
              
              Parameters: {$count}
Return Success: TRUE
Return Failure: FALSE
Purpose: API Method - See FT_SetResetPipeRetryCount().

StopInTask


            
              
              Parameters: None
Return Success: TRUE
Return Failure: FALSE
Purpose: API Method - See FT_StopInTask().

RestartInTask


            
              
              Parameters: None
Return Success: TRUE
Return Failure: FALSE
Purpose: API Method - See FT_RestartInTask().

Purge


            
              
              Parameters: {$mask}
Return Success: TRUE
Return Failure: FALSE
Purpose: API Method - See FT_Purge().

Read


            
              
              Parameters: {$bytesToRead}
Return Success: $bytesReturned, $readBuffer
Return Failure: undef
Purpose: API Method - See FT_Read().
Note: The method treats the returned buffer content as an opaque scalar value. Any translation
of strings or unpacking of binary content must be done by the application.

Write


            
              
              Parameters: {$writeBuffer} [, $bytesToWrite]
Return Success: $bytesWritten
Return Failure: undef
Purpose: API Method - See FT_Write().
Note: The method treats the write buffer content as an opaque scalar value. Any translation
of strings or packing of binary content must be done by the application.
If $bytesToWrite is not specified, the method will use the return of 'length($writeBuffer)'.
If $bytesToWrite is specified, it allows sending a full or partial buffer; however, the result
of sending more bytes than are in the buffer is undefined.

GetLatencyTimer


            
              
              Parameters: None
Return Success: $timer
Return Failure: undef
Purpose: API Method - See FT_GetLatencyTimer().

SetLatencyTimer


            
              
              Parameters: {$timer}
Return Success: TRUE
Return Failure: FALSE
Purpose: API Method - See FT_SetLatencyTimer().

GetBitMode


            
              
              Parameters: None
Return Success: $mode
Return Failure: undef
Purpose: API Method - See FT_GetBitMode().

SetBitMode


            
              
              Parameters: {$mode}
Return Success: TRUE
Return Failure: FALSE
Purpose: API Method - See FT_SetBitMode().
Note: The following EXPORTS for BitModes are available for convenience:
  PFT_BITMODE_RESET
  PFT_BITMODE_ASYNCBB
  PFT_BITMODE_MPSSE
  PFT_BITMODE_SYNCBB
  PFT_BITMODE_MHBEM
  PFT_BITMODE_FOISM
  PFT_BITMODE_CBUSBB

SetUSBParameters


            
              
              Parameters: {$inTransferSize, $outTransferSize}
Return Success: TRUE
Return Failure: FALSE
Purpose: API Method - See FT_SetUSBParameters().

P5VERSION


            
              
              Parameters: None
Return Success: $PFT_DLL_VERSION
Return Failure: undef
Purpose: Accesor Method - returns the version of the P5FTD2XX DLL in use.

VERSION


            
              
              Parameters: None
Return Success: $FTD2XX_MODULE_VERSION
Return Failure: undef
Purpose: Accesor Method - returns the version of the FTD2XX.pm in use.

PFT_HANDLE


            
              
              Parameters: None
Return Success: $PFT_HANDLE
Return Failure: undef
Purpose: Accesor Method - returns the numeric PFT_HANDLE allocated by the 
P5FTD2XX library which identifies the object's unique connection and state
information store.

PFT_STATUS


            
              
              Parameters: None
Return Success: $PFT_STATUS
Return Failure: undef
Purpose: Accesor Method - returns the enumerated status/error values of the last
method call (see FT and PFTE extensions in EXPORTS). In addition to the FT status
types, the PFT specific error types are: 
PFTE_INVALID_API - Requested API not in P5FTD2XX.DLL - usually a bug on my part, or the
  P5FTD2XX.DLL can't be found in the system PATH (default: "%SystemRoot%\System32")
PFTE_INVALID_HANDLE - The PFT_HANDLE passed is not valid (also usually a bug on my part)
PFTE_MAX_HANDLES - You've allocated max objects/PFT_HANDLES from the P5FTD2XX interface
PFTE_WAIT_TIMEOUT - error type for 'waitForModem' method on timeout only

PFT_STATUS_MSG


            
              
              Parameters: [$PFT_STATUS]
Return Success: $PFT_STATUS_MSG
Return Failure: undef
Purpose: Accesor Method - translates the enumerated FT_STATUS/PFT_STATUS values into
text equivalent for ease of generating error output. If a specific $PFT_STATUS is not 
provided, the method assumes the current state.

PFT_ERROR


            
              
              Parameters: None
Return Success: $PFT_ERROR
Return Failure: undef
Purpose: Accesor Method - some methods may have extended error information regarding the
failure reported in the (P)FT_STATUS types, and are returned here.

PFT_DEBUG


            
              
              Parameters: {TRUE|FALSE}
Return Success: $previousState
Return Failure: undef
Purpose: Accesor Method - some methods may have extended runtime debug information that
can be sent to STDERR when this variable is set to TRUE.

DEPENDENCIES

The FTDI/FTD2XX Drivers, at least CDM 2.04.06, must be installed in conjunction with this module for it to be functional (and, obviously, to get very far, you'll need an FTDI device plugged into your USB bus...)

The perl object uses Win32::API (v0.55 on my ActiveState 5.8.8 build) to interface with the P5FTD2XX DLL.

BUGS and THINGS TO DO

Please report bugs to me at my email address below.

See the BUGS file in the distribution for known issues and their status.

Things to Do

1) The FT_EVENT features have not been ported, and may or may not be, depending on demand (see the 'waitForModem' method instead for now).

2) Complete the DeviceInfoList/Detail Classic APIs.

3) Complete the EEPROM API interface.

4) Win the lottery, buy an island and retire ...

AND... if anyone is really just peeing their pants for a particular function that I haven't provided or ported yet, let me know and I'll see what I can do with the time I have.

AUTHOR

Scott K. MacPherson <skmacphe@cpan.org>

COPYRIGHT AND LICENSE

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.8 or, at your option, any later version of Perl 5 you may have available.

To install Win32::FTDI::FTD2XX, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Win32::FTDI::FTD2XX

CPAN shell

perl -MCPAN -e shell
install Win32::FTDI::FTD2XX

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)