usb_serial

USB Serial

Author Albert Faber, Copyright © 2009..2021, all rights reserved.
Adapted-by Rob Jansen
Compiler 2.5r5

Description

The library will ease the use of for serial communication over 
the USB interface. By default nothing has to be defined by the user, below
an example how to use the library


                                                                        
include usb_serial
..
usb_serial_init()
..
;-- optionally wait till USB becomes available
while ( usb_cdc_line_status() ==  0x00 )  loop
end loop
..
;-- main loop
var byte ch
forever loop
;   -- Call the flush routine on a regular base in the main loop
;   -- in order to keep the USB communicaiton alive.
;   -- This is only needed when USB_INTERRUPT_DRIVEN is not defined, otherwise
;   -- the usb_serial_flush() is not needed, see notes.
; 
    usb_serial_flush()
    if ( usb_serial_read( ch ) )
        usb_serial_data = ch -- echo
     end if
       .....
end loop


                                                                        
In addition this library can be used in combination with other JAL
libraries, like print.jal and format.jal, for example to send a
string, one can use the following code fragment:


                                                                        
const byte str[] = "Hello World"
print_string( usb_serial_data, str )


                                                                        
customization
The usb_serial library offers the following custimization prameters, 
the user has the ability to set these const parameter(s) before the 
inclusion of the usb_serial file


                                                                        
const byte USB_CDC_RX_BUFFER_SIZE = 0x??  -- set receive FIFO size
const byte USB_CDC_TX_BUFFER_SIZE = 0x??  -- set transmit FIFO size
const word USB_SERIAL_PRODUCT_ID = 0x???? -- set USB device product ID
const word USB_SERIAL_VENDOR_ID = 0x????  -- set USB device vendor ID
const byte USB_STRING0[] = { .. }         -- set USB language string
const byte USB_STRING1[] = { .. }         -- set USB mfg string
const byte USB_STRING2[] = { .. }         -- set USB product string


Notes

There are two options to use the USB driver for serial:
       1) Without interrupts by frequently calling 'usb_serial_flush()' 
          frequently in the main loop.
       2) Using interrupts. In that case no calls to 'usb_serial_flush()' are
          needed. This can be activated by defining
             const USB_INTERRUPT_DRIVEN = TRUE    


Dependencies


Summary

Global variables/contants

Procedures

Functions

Private

API details

Global variables/contants

Procedures

  • usb_serial_data'put(byte in data)

    usb_serial_data'put - write char to the USB port, blocking
    
    Asynchronuous serial send routine, using the USB Cummunication class
    Sends byte X (8 bit) to the USB host (via virtual COM port)
    Note that characters are dropped when the communcation channel on the
    USB host side is not opened (yet), this is a design choice in order to
    avoid lockup(s)
    
    

  • usb_serial_init()

    usb_serial_init will setup the USB communication, however, this can be
    a time consuming process, therefore this call is non blocking.
    In order to check if the USB device has established contact with the 
    HOST USB device, one can call the usb_is_configured() function, see
    usb_is_configured() documentation for additional details.
    
    

  • usb_serial_flush()

    usb_serial_flush shall be called on a regular base (millisecond range)
    in order to keep the USB transmision alive. Therefore it is adviced to
    call the usb_serial_flush procedure in the main loop of your 
    application. 
    Note: Only needed when USB interrupt is not used otherwise this call
    can be omitted (it does nothing in interrupt mode).
    
    

  • usb_serial_write(byte in data)

    usb_serial_write - write char to the USB port, blocking
    
    Asynchronuous serial send routine, using the USB Cummunication class
    Sends byte X (8 bit) to the USB host (via virtual COM port)
    Checks (and waits if necessary) if FIFO buffer is full
    Note that characters are dropped when the communcation channel on the
    USB host side is not opened (yet), this is a design choice in order to
    avoid lockup(s)
    
    

Functions

  • usb_serial_data'get() return byte

    usb_serial_data'get() - read a char (blocking!)
       
    usb_serial_data'get() waits till a character has been received and
    returns it
    
    

  • usb_serial_data_available'get() return bit

    No documentation found

  • usb_serial_port_open'get() return bit

    Check if the serial port has been opened by the host.
    
    

  • usb_serial_read(byte out data) return bit

    usb_serial_read - read char if available (non-blocking)
       
    usb_serial_read returns true if a character has been received, 
    otherwise returns false. If function returns true, the data variable
    is valid, and contains the character that has been received. In other
    cases the data variable is not defined
    Note that characters are dropped when the communcation channel on the
    USB host side is not opened (yet), this is a design choice in order to
    avoid lockup(s)
    
    

Private
  • _usb_serial_read(byte out data) return bit

    _usb_serial_read - internal use only!
    
    _usb_serial_read returns true if a character has been received, 
    otherwise returns false. If function returns true, the data variable
    is valid, and contains the character that has been received. In other
    cases the data variable is not defined
    Note that characters are dropped when the communcation channel on the
    USB host side is not opened (yet), this is a design choice in order to
    avoid lockup(s)
    
    



Related samples

Here are the list of samples which use this library:

16f145516f1455_usb_serial.jal
16f145516f1455_tutorial_usb_serial.jal
18f14k5018f14k50_usb_serial.jal
18f245018f2450_usb_serial.jal
18f255018f2550_usb_serial.jal
18f25k5018f25k50_usb_serial.jal
18f455018f4550_usb_serial.jal
18f455018f4550_ir2serial.jal
18f455018f4550_slip_poll_usb.jal
18f67j5018f67j50_usb_serial.jal
18f67j5018f67j50_slip_poll_usb.jal