Read Me

Thank you for downloading the MicroConnector library and giving it a try.
If you have any questions, comments, feature requests or bug reports
please let me know.

Chuck Bigham,
December, 2011
chuck(at)bramblyhill(dot)com

---- [ Copyright ] --------------------

Copyright (C) 2007, Chuck Bigham


This work is licensed under the Creative Commons 
Attribution-Noncommercial-Share Alike 3.0 United States License. 
To view a copy of this license, visit 
http://creativecommons.org/licenses/by-nc-sa/3.0/us/ 
or send a letter to 
   Creative Commons, 
   171 Second Street, Suite 300, 
   San Francisco, California, 94105, USA.
   
There are human-readable and legal versions of the license
available on the above Web site, but here is my short form:

  * Use, abuse, and change my code as you see fit. 

  * If you use my code in your application let people know.
  
  * If you make money off my code, I want my cut.

  * I shared my code, you share yours.
  
Please include the following in all derived works:
  Contains code originally written by Chuck Bigham.

---- [ Introduction ] -----------------

The objects in this library grew out of a discussion on the
Rev-Ed microcontroller forum (http://www.picaxeforum.co.uk/showthread.php?t=7996).

The idea is to create "a system that can control devices anywhere 
in the world using a microcontroller to interface to a PC and the internet 
to ftp some simple data packets to and from a common location."
Dr_Acula posted some code for a simple application, I volunteered
to take his ideas and create .NET objects that others can use to
create these interface applications.

There are three objects that create the microcontroller to PC to Web to
PC to microcontroller interface. 

  * The SerialConnector object listens to a microcontroller connected 
    to a serial port on the host PC and creates message objects.
  
  * The WebSender object queues message objects and uploads
    them to a shared FTP site as message files.
    
  * The WebReceiver object downloads message files from the
    shared FTP site and creates message objects.
    
  * The SerialConnector object sends message objects to
    a microcontroller connected to a serial port on the host PC.
    
The library also includes the SerialListener object for 
applications that only need one-way communications from the 
microcontroller to the host PC.

You can use these objects to create a wide variety of applications
that communicate with microcontroller chips and networks of microcontroller chips.
Included in this version of the library is the MicroBridge
application, a Windows application that acts as a bridge between
a microcontroller connected via a serial port and an FTP Web repository.

At the center of all these communications objects is the 
Message object. This object encapsulates the messages
passed between the other objects, and provides properties
for reading destination and source addresses, and message
data. Using the Message object you can view the 
individual sections of the message (destination address,
source address, and message data) as well as the message
as a whole. You can view all of these as strings, delimited
strings, or as byte arrays depending on the needs of your
application. The Message object supports messages
with any size address fields, as well as any size data field.
The size of the address and data fields can be set with
properties on the Message object. 

The only restriction is that Message objects created
from messages downloaded from the Web repository must have
the destination and source addresses be the same length. 
Changing the Message object to support messages with
different length address fields would require a change to 
the message data file naming convention established by
Dr_Acula in his original VB code.

---- [ Changes ] ----------------------

If you've downloaded earlier versions of these files from the Picaxe
forum site you'll notice some changes to the objects.

2007-11-21 changes:

	* Created a base "Sender" class that the WebSender
	  class inherits from. Creating the base class made it easier
	  for me to add additional sender classes, such as:
	  
	* Added a new UDPSender class that will send and receive
	  data to a specified UDP port and host.

	* Changed the copyright in the code files to match the
	  copyright in this file and in the "COPYING" file.


----[ Library contents ] --------------

The zip file contains the following directories:

	MicroBridge - C# source code for a Windows application
				   that acts as a bridge between a Picaxe
				   network and a Web message repository.
				    
	MicroConnector -    The C# source code for the library.
	
	MicroConnector-VB - VB source code for the MicroConnector library.
				   This code implements the same objects as
				   the C# code in the MicroConnector directory.
				   
				   
---- [ Installation instructions ] ----

Simple extract all the files from the ZIP archive to 
the directory of your choice. The solution and project
files were created in SharpDevelop and Visual Studio 2005;
they will also work with Visual Basic Express and 
Visual C# Express.

The top level MicroConnector file contains the Visual Studio
solution file MicroConnector.sln. This file can be opened by
Visual Studio or SharpDevelop and combines all of the
project files into one.

If you are using Visual Basic Express or Visual C# Express
you need to open the MicroConnector.csproj, MicroConnector.csproj,
or MicroConnector-VB.vbproj files included in each of the 
solution subdirectories.

After opening the solution or project, run the Build
operation to build the libraris and/or application.
You can also add the projects to an existing project
or solution if you want.

---- [ Sample microcontroller code ] -----------

I use the following microcontroller code to test the MicroBridge
object. It creates a packet of information, sends it to
the serial port, and then waits to receive a packet
of information back. The microcontroller then adds one to the last
byte of the address and echoes the packet back out the
serial port.

You need to configure the values stored in B0, B1, B2 to
match the MessagePrefix value you set in the MicroBridge
object.

#microcontroller 18X
' Simple serial echo program to use with the 
' MicroBridge demonstration program.

SYMBOL Red = 2   ' Red LED on ouput 2.
SYMBOL Green = 3 ' Green LED on output 3.

SYMBOL netSerialIN  = 6 ' Network serial input.
SYMBOL netSerialOUT = 0 ' Network serial output.

SYMBOL BaudRate = N2400

	PAUSE 5000

PowerOnReset:

' Set these to the message prefix you want
' to use for your network. It must match
' the setting used for the MicroBridge 
' application.

	B0 = $70 ' "p", decimal 112.
	B1 = $68 ' "h", decimal 104.
	B2 = $6E ' "n", decimal 110.

	SEROUT netSerialOUT, N2400, (B0,B1,B2,$00,$70,$68,$6E,$FF,$30,$31,$32,$33,$34,$35 )
	
main:

	PAUSE 500

	TOGGLE Red ' Red LED on while we wait for serial data.
	
	SERIN netSerialIn, N2400, B0,B1,B2,B3,B4,B5,B6,B7,B8,B9,B10,B11,B12,B13
	
	TOGGLE Red ' Red LED off when data has arrived.
	
	TOGGLE Green ' Show that we're waiting to send.
	
	PAUSE 5000
	
	INC B3
	
	SEROUT netSerialOut, N2400, (B0,B1,B2,B3,B4,B5,B6,B7,B8,B9,B10,B11,B12,B13)
	
	PAUSE 500
	
	TOGGLE Green;
	
	GOTO Main
	
---- [ Known issues ] -----------------

2007-10-24: These are the known issues in this release:

  *  WebSender and WebReceiver do not have matching
     properties that they should have. For example, the receiver 
     has a path property to retrieve messages from subdirectories
     of the FTP site, the sender does not have a path property 
     so it can only put messages in the root directory of the
     FTP site.
     
  *  I need to create a VB version of the MicroBridge application
     since the original need for this library was to support 
     VB.NET programmers and applications.
     
  *  The whole library needs more testing. What I've tested 
     works, but I know I've missed something.
     
---- [ Feature work ] -----------------

Here are the new features I'm considering for future versions:

   *  A simple "terminal" program for sending and receiving
      strings to and from the Picaxe. 
      
   *  A "terminal" control that can be added to any Windows
      application.
      
   *  A version of the bridge application that runs as a 
      Windows service.