HAPSIM - Programmer's Tutorial

Downloads needed:

Adding new controls to HAPSIM:

Every control consists of

• a Document class derived from CHapsimDoc, e.g. CNewControlDoc
  The only member function this class must have is
  

    virtual void Serialize(CArchive *pArch);

  which can be copied from any other control without change.
  
  
• a View class derived from any basic view class you like (CView, CFormView,...), e.g. CNewControlView
  This is the place where you add all the functionallity of the new control.
  The only mandatory member function is
  

    void Serialize(CArchive *pArch);

  which is called from your Document class for serialization.
  
  You have to bind your new doc/view classes to the HAPSIM application by adding a new DocTemplate within the InitInstance() function of the ChapsimApp class. e.g.
  

     pDocTemplate = new CHapsimDocTemplate(
        IDR_NEWCONTROLTYPE,
        RUNTIME_CLASS(CNewControlDoc),
        RUNTIME_CLASS(CChildFrame), // custom MDI child frame
        RUNTIME_CLASS(CNewControlView));
     AddDocTemplate(pDocTemplate);
  

• a Serializer class, e.g. CNewControlSerializer ... but DON'T edit this class! It's generated!
  HAPSIM uses an overall serialization concept for storing a whole configuration with all the used controls into a single XML file.
  For simplification there is a special code generator named hxs.exe which generates your Serializer class.
  A header file NewControlHxsData.h is used as input for this code generator and that's the place where you should define the structure of the data you want to have written to the config file. It must be one main structure that may have substructures and only the data types defined in hxsTypes.h are allowed here!
  Just have a look at one of the existing files e.g. LedHxsData.h and compare to the XML file stored by HAPSIM to understand the concept!
  
  You can regenerate your serializer class any time by entering the command line:
  >hxs NewControlHxsData.h
  
  Your view will receive a WM_CONFIGLOADED msg. -> leads to OnConfigLoaded() after a config file has been loaded.

How to interface with AvrStudio:

To get your view informed about a change of PORT output pins of the AVR you have to register your view via a call to

   theApp.SetViewList(this, register-address, bitmask-value);

Then your view gets informed by a WM_AVRPORT message whenever one of the specified bits of the selected register has changed -> leads to OnAvrRegChange where lParam is the new value of the register.

Change the value of an AVR Input register via a call to

   theApp.m_hook.AvrRegWrite(addr, value, 1, REG_INPUT or REG_BOTH);

REG_INPUT is only sufficient when you are sure that the AVR-Simulator of AVRStudio is in waiting state which is the case after receiving a register change before calling the AvrResetBusy() function.
When you want to write PIN registers asynchronously you must write to both register banks of the Simulator (REG_BOTH) because AVR Simulator copies a lot between these two banks.
Just have a look at the existing controls to see how it works...

AvrTimer: Via a call to

   theApp.m_timer.StartTimer(this, delay);

your view will get informed by a WM_AVRTIMER message after the expiration of 'delay' clock cycles inside the AVR Simulator.
With this mechanism you can synchronize your simulation task to the real AVR clock cycles!

Integration into the Official Release:

If you made changes and you think they might be useful for others too then please send me the new and modified files and I would be glad to integrate them into a new official release of HAPSIM!
Also don't hesitate to e-mail to helmix@gmx.at if you have questions or problems with your implementation.

Helmut Wallner, 5.5.2007

Home