Simple Serial Object Version 1.4


******************************************************************* * Simple Asynchronous Serial Driver v1.4 * * Authors: Chip Gracey, Phil Pilgrim, Jon Williams, Jeff Martin * * Copyright (c) 2006 Parallax, Inc. * * See end of file for terms of use. * ******************************************************************* v1.4 - July 18, 2012 - Added extra comments to bring up to autodoc gold standard (msrobots) v1.3 - May 7, 2009 - Updated by Jeff Martin to fix rx method bug, noted by Mike Green and others, where uninitialized variable would mangle received byte. v1.2 - March 26, 2008 - Updated by Jeff Martin to conform to Propeller object initialization standards and compress by 11 longs. v1.1 - April 29, 2006 - Updated by Jon Williams for consistency. The init method MUST be called before the first use of this object. Optionally call finalize after final use to release transmit pin. Tested to 19.2 kbaud with clkfreq of 80 MHz (5 MHz crystal, 16x PLL)

Introduction

This driver, once started, implements a serial port in one cog. Performs asynchronous serial input/output at low baud rates (~19.2K or lower) using high-level code in a blocking fashion (ie: single-cog (serial-process) rather than multi-cog (parallel-process)). ' To perform asynchronous serial communication as a parallel process, use the FullDuplexSerial object instead. '

Connection Diagram

┌─────────┐ │ │ │ rxPin├─── TTL level RX line │ txPin├─── TTL level TX line │ │ └─────────┘ Propeller MCU (P8X32A) EXAMPLES: Standard Two-Pin Bi-Directional True/Inverted Modes Standard One-Pin Uni-Directional True/Inverted Mode Ex: serial.init(0, 1, ±9600) Ex: serial.init(0, -1, ±9600) -or- serial.init(-1, 0, ±9600) ┌────────────┐ ┌──────────┐ ┌────────────┐ ┌──────────┐ │Propeller P0├─────────────┤I/O Device│ │Propeller P0├───────────────┤I/O Device│ │ P1├─────────────┤ │ └────────────┘ └──────────┘ └────────────┘ └──────────┘ Same-Pin (Bi-Directional) True Mode Same-Pin (Bi-Directional) Inverted Mode Ex: serial.init(0, 0, 9600) Ex: serial.init(0, 0, -9600)  ┌────────────┐ ┌──────────┐ │ │Propeller P0├─────┳─────┤I/O Device│  4.7 kΩ └────────────┘ │ └──────────┘ ┌────────────┐ │ ┌──────────┐  4.7 kΩ │Propeller P0├─────┻─────┤I/O Device│ │ └────────────┘ └──────────┘ 

Public Spin methods

Start and Stop

Start and Stop methods are used for starting and stopping this object. This uses/frees one cog and the rx/tx-pins used.


Stop

Call this method after final use of object to release transmit pin.

SOURCE CODE...
PUB Stop
 
  if txOkay                                             ' if tx enabled
    dira[sout]~                                         '   float tx pin
  rxOkay := txOkay := false


Start(rxPin, txPin, baud)

Call this method before first use of object to initialize pins and baud rate.

  • For true mode (start bit = 0), use positive baud value.     Ex: serial.init(0, 1, 9600)
    For inverted mode (start bit = 1), use negative baud value. Ex: serial.init(0, 1, -9600) 
  • Specify -1 for "unused" rxPin or txPin if only one-way communication desired.
  • Specify same value for rxPin and txPin for bi-directional communication on that pin and connect a pull-up/pull-down resistor
    to that pin (depending on true/inverted mode) since pin will set it to hi-z (input) at the end of transmission to avoid
    electrical conflicts.  See "Same-Pin (Bi-Directional)" examples, below.


SOURCE CODE...
PUB Start(rxPin, txPin, baud): Okay

  Stop                                              ' clean-up if restart
  
  rxOkay := rxPin > -1                                  ' receiving?
  txOkay := txPin > -1                                  ' transmitting?

  sin := rxPin & $1F                                    ' set rx pin
  sout := txPin & $1F                                   ' set tx pin

  inverted := baud < 0                                  ' set inverted flag
  bitTime := clkfreq / ||baud                           ' calculate serial bit time  
  
  return rxOkay | TxOkay


Basic send/receive

Here you find basic send/receive-methods for single bytes.


Rx

Receive a byte; blocks caller until byte received.

SOURCE CODE...
PUB Rx: rxByte | t

  if rxOkay
    dira[sin]~                                          ' make rx pin an input
    waitpeq(inverted & |< sin, |< sin, 0)               ' wait for start bit
    t := cnt + bitTime >> 1                             ' sync + 1/2 bit
    repeat 8
      waitcnt(t += bitTime)                             ' wait for middle of bit
      rxByte := ina[sin] << 7 | rxByte >> 1             ' sample bit 
    waitcnt(t + bitTime)                                ' allow for stop bit 

    rxByte := (rxByte ^ inverted) & $FF                 ' adjust for mode and strip off high bits


Tx(txByte)

Transmit a byte; blocks caller until byte transmitted.

SOURCE CODE...
PUB Tx(txByte) | t

  if txOkay
    outa[sout] := !inverted                             ' set idle state
    dira[sout]~~                                        ' make tx pin an output        
    txByte := ((txByte | $100) << 2) ^ inverted         ' add stop bit, set mode 
    t := cnt                                            ' sync
    repeat 10                                           ' start + eight data bits + stop
      waitcnt(t += bitTime)                             ' wait bit time
      outa[sout] := (txByte >>= 1) & 1                  ' output bit (true mode)  
    
    if sout == sin
      dira[sout]~                                       ' release to pull-up/pull-down


Extended send/receive

Here you find extended send/receive-methods. This serial object has just one extended send-methods.
You can use it for output of strings.


Str(strAddr)

Transmit z-string at strAddr; blocks caller until string transmitted.

SOURCE CODE...
PUB Str(strAddr)

  if txOkay
    repeat strsize(strAddr)                             ' for each character in string
      tx(byte[strAddr++])                               '   write the character


depriciated

these Methods are depriciated and kept for backward-compability


finalize


SOURCE CODE...
PUB finalize
RETURN Stop


init(rxPin, txPin, baud)


SOURCE CODE...
PUB init(rxPin, txPin, baud)
RETURN Start(rxPin, txPin, baud)


Global VARiables


SOURCE CODE...

  long  sin, sout, inverted, bitTime, rxOkay, txOkay   


License

┌──────────────────────────────────────────────────────────────────────────────────────┐
│                            TERMS OF USE: MIT License                                 │                                                            
├──────────────────────────────────────────────────────────────────────────────────────┤
│Permission is hereby granted, free of charge, to any person obtaining a copy of this  │
│software and associated documentation files (the "Software"), to deal in the Software │
│without restriction, including without limitation the rights to use, copy, modify,    │
│merge, publish, distribute, sublicense, and/or sell copies of the Software, and to    │
│permit persons to whom the Software is furnished to do so, subject to the following   │
│conditions:                                                                           │
│                                                                                      │
│The above copyright notice and this permission notice shall be included in all copies │
│or substantial portions of the Software.                                              │
│                                                                                      │
│THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,   │
│INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A         │
│PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT    │
│HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF  │
│CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE  │
│OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.                                         │
└──────────────────────────────────────────────────────────────────────────────────────┘