Setting the realtime clock from your PC

This EasyStep will show you how to set the time in your EC1 from the time in your PC. It's quick and it's easy. You will also learn how to incorporate the tiny bit of required SPLat code into your own SPLat programs.

It should take you no more than an hour to go through this, providing you already understand the fundamentals of SPLat programming.

The EC1 is unique among very low cost microcontroller boards in that it has an onboard calendar/clock, often called RealTime Clock (RTC). The RTC provides a full calendar and time of day clock, as well as advanced features like programmable events that can be set to go off at specified times on selected days of the week. In short, the RTC has enough features to let you program elaborate time-clock functionality into your EC1-based project.

Note: Don't confuse the RTC with the basic ability to generate time intervals. SPLat has a rich set of interval related instructions like Pause, which handle the passage of time. These don't exist as native functions in most other microcontroller boards. The RTC takes it to a higher level again by knowing what the date and time are.

What you will need

• An EC1 all ready to plug into your PC via USB;
• SPLat/PC installed and running, and the basic skills to enter and download programs.

Before starting on this, please be sure to have completed the EasyStep Connecting a battery to your EC1 for the realtime clock

The RTC setting capability is contained within the SimpleHMI client in SPLat/PC. The SimpleHMI has a button next to the SimpleHMI screen. When clicked it will set the date and time to a connected EC1. If the EC1 is running a tiny bit of special code, the result will be that the RTC in the EC1 is set to the time and date in your PC.

The bare bones

# Open_Serial User(38400, 8, N)  ;Goes to SimpleHMI in the PC (inside SPLat/PC or standalone version)	
# HMI SetRTCEvent()

The first line opens the default communications port, which is the USB programming port, and makes it available for use by your program. There is a 10 second delay before that comes into effect (the reason for that delay should be clear shortly).

The second line causes a whole pile of under-the-hood code to be activated, which provides the capability of receiving a time-setting message from the SimpleHMI device (in this case the PC) and updating the onboard RTC with time and date.

A more elaborate template program

The above two lines of code have one drawback: SPLat/PC, and the SimpleHMI client that you can run from inside SPLat/PC, are two quite separate entities. Once the communications port has been opened for SimpleHMI use by the running application, it is no longer available to SPLat/PC for programming the board. The only away to give control back to SPLat/PC is to restart the program and the hit the Stop button in the SPLat/PC Module window within 10 seconds. There are two ways to restart the program:

• Cycle the power, by unplugging and re-plugging the USB (assuming you are powering the board off USB). Then hit the Stop button within 10 seconds. This method is inconvenient. Also, the USB drivers in Windows get upset by unplugging, and it may be difficult to get the PC to re-activate the port within 10 seconds;
• Do a bit of skullduggery in the SPLat program so it can be forced to crash. This always forces a restart of the program.

The following program does a number of things

• At startup it turns on both LEDs and waits for you to press the button on the EC1. While both LEDs are on you can click the Stop or Connect buttons on the SPLat/PC Module window, and get connected to the board;
  
• The green LED flashes to tell you the program is running ("heart beat"). This will not happen until 10s after the program started and the EC1 button has been pressed;
• Any subsequent short press on the EC1 push button forces the RTC to be updated from the SimpleHMI client in SPLat/PC;
• A click of the Set RTC button on the SimpleHMI window in SPLat/PC also forces the RTC to be updated;
• The red LED flashes briefly when the RTC time and date are sent from SimpleHMI;
• A long (2s) press on the EC1 push button deliberately crashes the program (Kill switch function). The program restarts, turns on both LEDs and will respond to the Stop or Connect buttons on the SPLat/PC Module window;

The full program is listed below, with extensive annotations. To show/hide the program listing click here. There are pop-ups for each major functional block of code, and clickable links on individual instructions that take you to the formal descriptions of the instructions.

The block annotations are marked like this:

Place your mouse over that line to see a pop-up describing the overall logic of the block.

Many instruction also have clickable links to the formal definition online. (Tip: Click the link with your mouse wheel to open in a new browser tab)

Please invest some time studying the program. Even if you don't understand all the details, try to at least get the general drift of what the major blocks are all about.

;========== Demo: Setting RTC in an EC1 from SimpleHMI	====================																									
;[...]
iButton        iEQU             0         ;Give the EC1 button a recognisable name
oRedLED        oEQU             1         ;Give the EC1 red LED a recognisable name
oGreenLED      oEQU             0         ;Give the EC1 green LED a recognisable name

;[...]
;Turn on both EC1 LEDs then wait for a button press.													
;This provides a trap for any crashes, and makes it easy to detect a crash and connect to SPLat/PC		
                On              oRedLED																				
                On              oGreenLED																				
                WaitOnK         iButton 																				
                Off             oRedLED																				
                Off             oGreenLED	
  
;[...]
;The default serial port needs to be opened in User mode to allow SimpleHMI 
;communication with the PC        
# Open_Serial  User(38400, 8, N)       ;Goes to SimpleHMI in the PC (inside SPLat/PC)	
																										
;[...]
;Declare the handler for the SetRTCEvent, which happens when the PC sends us RTC data																										
# HMI  SetRTCEvent(MyRTCHandler)

;[...](Don't yet know what MultiTrack is? See 32 processes for the price of one)
;Launch the tasks required																		
                LaunchTask              FetchIt        ;Task that lets the enduser get an RTC update
                LaunchTask              HeartBeat      ;Flashes a LED to show we are alive      
                LaunchTask              KillSwitch     ;Makes the EC1 button into a killswitch
                RunTasksForever				;Start the tasks running
																			
;------  RTC update request task -------------------------------
;This task asks the SimpleHMI client to send RTC data whenever the EC1 button is pressed
FetchIt:
                WaitOnK         iButton   ;Wait for the button
# HMI GetRTC()                          ;Ask SimpleHMI to send a date/time update
                GoTo            FetchIt
				
;------  HeartBeat task -------------------------------
;This task flashes the green LED just to show the program is running.                
HeartBeat:
                On              oGreenLED
                Pause           10
                Off             oGreenLED
                Pause           40
                GoTo            HeartBeat

;------  KillSwitch task -------------------------------
;This task kills the program if the EC1 button is held on for 2s.
;This allows to SPLat/PC to regain control (Click Stop on the Module window)
KillSwitch:
                WaitOn         iButton     ;Wait for the button
                WaitOffT       iButton,200 ;Allow 2s for it to go off again
                GoIfT           KillSwitch ;g/ it went off within 2s
Die             GoSub           Die        ;deliberate crash.

;------- Event handler for RTC updates from SimpleHMI ---------                          
;Handle the SetRTCEvent. Flash the red LED to signal it was received.
;By the time we get here the RTC has been set to the date and time sent from 
;the SimpleHMI client (a.k.a. the PC, in this case)																									
MyRTCHandler:    
                On              oRedLED
                Pause           50
                Off             oRedLED
                Pause           10 
                Return

Take back control

When you have explored everything the program can do, you need to stop it running and give control of the EC1 back to SPLat/PC.

• Press and hold the EC1 button for 2 seconds. Both LEDs should come on. You have just triggered the killswitch function, and the program has restarted. Click the Stop button on the Module window of SPLat/PC (or the Connect button, if it is showing)
  

  The Module window should expand, and stay expanded.

  
  
• You will get a pop-up error message. This happens because the killswitch deliberately crashes the program. Dismiss the error message.

You have successfully stopped the program and given SPLat/PC control of the board, ready to change the program.

Crash trap

This is the first bit of code that will be executed when the program starts running. It will turn on both LEDs on the EC1, and then just sit and wait for you to press the button. (WaitOnK) before continuing.

The reason for this is a quite complicated. The executive summary is this:

If the program crashes, it will restart and come back to this point, turning on the two LEDs. You can then connect via the Connect or Stop button in the SPLat/PC Module window, and SPLat/PC will display a message describing the cause of the crash.

  

While the program is running the programming port is assigned to the SimpleHMI function, and the Connect button will not work. For this reason you will see later that we also have a mechanism for deliberately crashing the program, called a "killswitch"