Coal Basin Buttons 2

Summary of class library.

Include File: <Coal_Basin_Buttons2.>

Constructor:   Coal_Basin_Buttons2 button (uint8_t, unit8_t,uint8_t) where the 3 parameters define how circuit is wired.)

Public Methods: begin( )
            get_route( ) that returns status of the buttons.

---------------------------

Project Objective:

To capture the state of up to 16 buttons and to transfer these to a microcontroller. 

This page is part of larger model railway project illustrated below. 

----------------------

The Model Railway Layout

The model train layout is shown below. 

There is a control panel on which there are mounted buttons corresponding to the end locations Silos, Wharf 1 etc. The job of this project is to read the buttons. The overall project will take the information and control the appropriate points to permit a train to run on the chosen route.

-----------------------------
Circuit: Block Diagram

On the Load command from the NANO the status of the 16 buttons is read by the parallel to serial converters. The NANO then generates 16 clock pulses to transfer the button status into the microcontroller. The output result will be a 16bit number where each bit represents a pressed button

__________________

The Design Include Files

To not clutter the header file this project contains two include files:
1. Coal_Basin_States.h that contains definitions of all the possible states. For example #define SILOS 1, #define WHARF1 2 etc. These definitions are common to all of the Coal_Basin projects so a copy will need to be included in each project.

2, Coal_Basin_Buttons2_Wiring.h that accounts for how the buttons are wired.  To avoid crossovers in the PCB layout there is not a 1:1 relationship between the buttons and the numeric result in the micro-controller. That is reading the SILOS button will not give the required value of  "1" to match the States definition. The relationship between the buttons and their 16-bit code needs to be determined by testing and a map generated once the final hardware is available

The additional files need to have the extension *.h and for later convenience they should have a name that in alphabetic order falls after the name of the  main *.cpp and *.h files. See section on "Generating a Class/Library"

-----------------------------

The header file: Coal_Basin_Button2.h

The main features of the header file are

1. A class/library Coal_Basin_Buttons2.h is created.
               The constructor will be Coal_Basin_Buttons2 ( unit8_t,unit8_t, unit8_t) where the three parameters specify the microcontroller pins to which an object will be attached.
               The public functions will be begin( ); that performs all the initialization and  get_route( ) that returns the button that is pressed.

2. The included files Coal_Basin_States.h and Coal_Basin_Buttons2_wiring.h that document the state definitions and  the relationship between the physical buttons and the program definitions. This takes into account that the wiring between the actual buttons is not 1:1. The map is to be determined during testing process

----------------------------

The Implementation code: Coal_Basin_Button.cpp

The features of the implementation code are:

1. Implementation the constructor where the 3 wiring parameters load, clock and serial are assigned to private variables.

2. The public method begin( ) where the load and clock pins are assigned as outputs.

3. The public method get_route( ) that generates the load signal to read the status of the (16) buttons into the parallel to serial converters, sends 16 clock pulses to transfer the data to the micro controller as a 16 bit integer and calls the convert routine to generate the requested route which is returned to the calling method.  Since the active buttons are low the input bits as they are read are complemented.

4. The private method _convert(unsigned int buttons) that takes the new reading and uses the Coal_Basin_Buttons2_Wiring .h map to translate this into the desired request. (As defined in Coal_Basin_States.h.)

The get_route( ) method also includes a debug option that prints the reading as it is built to the monitor. To use set #define DEBUG 1

-------------------------------

Test/Client/Application/Demonstration *ino code 

For this example the *.ino file is a demonstration file to illustrate how the Coal_Basin_Button2 library may be used. It will

1. Create a new Object/Instance route1 of the Coad_Basin_Buttons2 class attached to pins 4 (load,) 5 (clock) and 6 (serial in)

2. In the set up method initialise call the begin routines to initialize the object route1 and the serial port that is used to demonstrate the output.

3. Continually call the get_route() method and display the new route requests. 

The get_route( ) method included code that would print the reading to the serial monitor as the result was built. Connecting the SERIAL_IN pin to ground simulates all buttons being pressed and the display show the result as the number is built up.  With SERIAL_IN connected to Vcc all readings will be zero.

The decimal results below are for the value of buttons before each new reading.  There will be one more reading after the 32767 and this is the value (shown in HEX) that is sent to the convert() method.

-----------------------------------

Testing with real hardware.

With no buttons pressed the  test results should be zero. Pressing any key should give what appears to be a random number. If either of these do not occur there is probably a hardware fault that will need to be found and corrected.

The next step is to work through each button in turn and determine the mapping. For example, pressing the silos button may give the result 128. It will then be a matter of modifying the Coal_Basin_Buttons2_Wiring.h  code to #define I_SILOS 128. Repeat this for all buttons.

---------------------

Generating a class library.

To use with other projects it will be necessary to generate a library. The best sequence is

1. Using File Explorer for example make a *.zip file of all the files. They will be in the folder Coal_Basin_Buttons2 that is under your Arduino work directory. The new file will have label Coal_Basin_Buttons2.zip (**)

2. In the Arduino IDE select <Sketch>  <Include Library> <add *.zip files> and select Coal_Basin_Buttons2.zip. This will create the library Coal_Basin_Button2 that will be under libraries in your Arduino work directory.

3. To use the library include the following in the new program #include <Coal_Basin_Buttons2.h>. With the "<..>" the compiler will look in the libraries folder.

(**) When creating the *.zip file it will be given the name of the first file.  The desired name will be Coal_Basin_Buttons2 so if necessary the name of the *.zip should be changed to Coal_Basin_Buttons2.  This will not be necessary if any additional header files have names that in alphabetical order fall after Coal_Basin_Buttons2. This was recommended in the "Design Include Files" section 

------------------------

Future Projects

This project will be used as the input to the Coal_Basin2 projects. The main elements are:

Coal_Basin_LED2 that controls the LEDs that display the chosen track.

Coal_Basin_Servos2 That generates signals to drive the points

Coal_Basin_Control2 that uses the button inputs to drive the LEDs and the required servos that control the points. ie Coal_Basin_Servo2.

--End of Project Description--