ObjectTeams/Java (OT/J) is an extension to Java programming language that facilitates roles and collaborations as the first class language constructs. This article is an exercise on using (OT/J) for implementing collaborations.

Subject area

This exercise considers two bank operations – money transfer and fund cashing. The course of events for these two operations is very similar in basic and differs in details. Considering this, it is implemented as an abstract withdraw routine leaving detail differences to concrete implementations.

An abstract withdraw routine

Figure 1

A withdraw routine executed in a bank allows to move funds from one account to another. The bank, which executes this operation, charges some fee, applied to the credit account and debited onto the bank’s operational account. When the currency of the operation is not the same as the bank’s native currency, the bank converts the fee to the native currency.
A collaboration diagram for this operation is given on Figure 1. The collaboration steps and reiterated below:

1. Calculate a fee for this operation
2. Charge the amount+fee from the credit account
3. Put the money on the debit account, which is expected to accept any currency
4. If the currency of the operation differs from the currency of the banks’ operational account conversion is applied to the fee
5. Put the fee is on the operational account

A function that implements this code is given below (for a complete class please refer to the source):

	protected final void withdraw(BigDecimal amount, CreditAccount creditAccount, DebitAccount debitAccount,
			OperationalAccount operationalAccount, CurrencyConverter currencyConvertor) {
		BigDecimal fee =  calculateFee(amount);
		creditAccount.credit(amount.add(fee));
		debitAccount.debit(amount,creditAccount.currency());
		if( creditAccount.currency() != operationalAccount.currency())
			fee = currencyConvertor.convert(creditAccount.currency(), operationalAccount.currency(), fee);
		operationalAccount.debit(fee);
	}

In this exercise, this method is implemented in scope of a team class Withdraw Collaboration and the parameter types are defined as role classes in the team. This class is pretty isolated and depends only on Currency class, so it can be reused in other applications. Details of the account implementations are hidden behind the roles.

Concrete withdrawal routines

A bank that implements concrete withdrawal routines, gives its clients two interfaces – the Cashier interface that allows people to get some cash from they accounts, and the Wire Operator interface that allows them to transfer funds from the account they have in this bank to any other account. In scope of this exercise, these two interfaces are implemented by two collaboration, both extending the Withdraw Collaboration. Each collaboration is instantiated in the bank for a given account and then returned to the client. Once the interface is provided, the client may execute more than one operation with the current account.
Since there could be a rather long thinking time, the bank can not provide an operational account at the time when the interface is acquired, but instead the operation account should be determined at the moment of transaction execution. To achieve this, these collaborations are extended with an additional role – Operator which provides access to the available operational account at the moment of transaction execution.
Additional complications with implementing the Cashier that there is not debit account available, since the money are given to a person and the person cannot accept a decimal value, he/she can only take cash, so the digits should be converted to cash. Code snippet for this operation is given below (for a complete class please refer to the source):

	public void giveCashTo(Person person, double amount) {
		BigDecimal value = new BigDecimal(amount);
		reserved = bank.acquireCash(value, account.currency());
		try {
			cashOperation(new BigDecimal(amount), account, person, bank, bank);
		}
		finally {
			if( reserved.value().signum() != 0 ) {
			// Recipient did not take the money
				bank.returnCash(reserved);
			}
		}
	}

To match the Person entity with the DebitAccount interface, a new role is defined as below:

	protected class CashRecipient extends DebitAccount playedBy Person {

		void takes(Cash cash) -> void takes(Cash cash);

		protected void debit(BigDecimal amount, Currency currency) {
			assert reserved.value() == amount && reserved.currency() == currency;
			takes(reserved);
		}
	}

Bank

In this exercise a bank has an internal operational account, and a safe, where all cash is kept. It provides methods for opening accounts (credit and current) and access to two already mentioned interfaces Cashier and Wire Operator. BankAccount is an protected inner class of the Bank to ensure that no one can create a bank account outside of a bank (for a complete class please refer to the source).

Cash

If everyone would be able to create cash in their own, there would be no need for banks and accounts . Also, when cash is being added or subtracted, its behavior differs very much from adding two numbers. To model these features of the cash, a dedicated class is provided. The only public constructor it provides creates zero cash. The add operation accepts Cash as the addendum and clears it after adding. The subtract operation accepts a number and creates a new cash for the amount of subtrahend. Also it provides an instruction to the garbage collector to report any occurrence of valuable cash in the garbage (for a complete class please refer to the source).

Modeling the plan

With the mentioned above classes (and some additional) we can now model Tom and Mary’s plan:
Entities that are assumed to exist:

	Bank spicer  = new Bank("JVM-Spicer,MN ", Currency.USD);
	Bank willmar = new Bank("OTJ-Willmar,MN", Currency.EUR);
	Bank bahama  = new Bank("Java-Bahamas  ", Currency.BSD);

	Person tom  = new Person("Tom ");
	Person mary = new Person("Mary");

The plan:

		Account credit = spicer.openCreditAccount(1000000, Currency.USD);
		Cashier cashier = spicer.cashier(credit);
		cashier.giveCashTo(tom, 970000);

		mary.takes(	tom.gives(965000, Currency.USD) );

		Account deposit = willmar.openAccount(mary.gives(960000,Currency.USD));

		Account bahamamama = bahama.openAccount(mary.gives(1000,Currency.USD));

		WireTransfer wire = willmar.wireOperator(deposit);
		wire.wireTo(bahamamama, 950000);

		cashier = bahama.cashier(bahamamama);
		cashier.giveCashTo(mary, 923000);

		tom.takes( mary.gives(461000, Currency.USD) );

All sources are available for downloading as a single archive under The GNU Lesser General Public License (LGPLv3).

Conclusion

Collaboration design pattern is a useful abstraction for designing the application. Implementing collaborations with a new, promising Java language extension facilitates using of the first class language constructs (teams) and significantly improves the separation of concerns letting the developer to concentrate on one task at a time.

The idea

If we look at Java classes, interfaces and references among them at the high level of abstraction, their appear to be a linked graph where classes/interfaces can be thought as nodes and references – as links between them. These thoughts, being turned inside out, lead to the following rationales: a graph can be represented as a set of interfaces where an interface represents a node and a reference to another interface represents a link. Such references, for instance, could be return types of methods defined in the interface.

Rationales

The following table lists rationales on graph representation.

Figure 1

Microwave automaton

Lets consider a simple microwave with one push-button and a knob timer. This microwave starts heating when the user pushes the button and the door is closed and the timer is set. Pushing button again stops heating, opening the door suspends heating until the door is closed again. A state chart for this microwave is shown on Figure 1. The following code snippet shows how this state chart can be represented with the rationales given above.

public class MicrowaveStateMachine {
  /**
   * In Door Open State MW waits until the door is closed
   */
  interface DoorOpenState extends State {
	  @OnEnter void enter	(DoDing a);                            	// on entering Door Open State issue a Ding action
	  WaitingState  idle   	(OnDoorClose e, IfTimerIsSet a);  		// on Door Close Event transit to Waiting State
	  HeatingState  resume 	(OnDoorClose e, IfTimerIsNotSet a); 	// on Door Close Event transit to Waiting State
	  DoorOpenState ignore 	(OnPushButton e, DoBeep a);          	// on Push Button Event issue a Beep and remain in DoorOpenState
	  @OnLeave void leave	(DoDong a);								// on entering Door Close State issue a Dong
  }
  /**
   * In Waiting State MW waits until a button is pushed
   * If timer is set, it starts heating, otherwise it beeps
   */
  interface WaitingState extends State {
	  HeatingState  start   (OnPushButton e, IfTimerIsSet c);		// on Push Button Event if timer is set transit to heating
	  WaitingState  beep    (OnPushButton e, IfTimerIsNotSet c, DoBeep a); // otherwise issue a Beep and remain in waiting
	  DoorOpenState open    (OnDoorOpen e);							// on Door Open Event transit to Door Open State
  }
  /**
   * In Heating state it actually heats.
   * On entering this state MW starts the heater and the cook timer;
   * On leaving this state MW stops the heater and suspends the cook timer
   */
  interface HeatingState extends State {
	  @OnEnter void enter	(DoStartHeater a, DoStartCookTimer t); 	// on entering HeatingState State issue Start Heater Action
	  WaitingState  timer	(OnCookTimerExpired e);					// on Timer Expired Event transit to Waiting State
	  WaitingState  stop	(OnPushButton e);						// on Push Button Event transit to WaitingState State
	  DoorOpenState open	(OnDoorOpen e);							// on Door Open Event transit to Door Open State
	  @OnLeave void leave	(DoStopHeater a, DoSuspendCookTimer b);	// on leave issue DoStopHeater
  }
}

Constructing run-time artifacts

Obviously, this is only definition and it requires, as well as an XML definition, some code to turn it into a run-time artifact. Java Reflection API provides all necessary means for examining the definition but producing a valuable output is an application specific task. In other words, the task is split on two concerns – (1) examining the definition and (2) generating the output. The source code sample attached to this article provides a utility class that implements first concern (Walker) and an application class (MicrowaveSample) that generates microwave automaton assembler code for a PICmicro MCU (see sample output below). Walker class exposes one method processAutomaton accepting a state chart definition class and communicates with MicrowaveSample via WalkerCallback interface implemented by MicrowaveSample.

;-----------------------------------------------------
DoorOpenState
    call DoDing
DoorOpenState_begin
    call sleepAndWaitEvents
DoorOpenState_0
    btfss OnDoorClose    ; resume
    bra DoorOpenState_1
    btfss IfTimerIsNotSet
    bra DoorOpenState_1
    call DoorOpenState_leave
    bra HeatingState
DoorOpenState_1
    btfss OnDoorClose    ; idle
    bra DoorOpenState_2
    btfss IfTimerIsSet
    bra DoorOpenState_2
    call DoorOpenState_leave
    bra WaitingState
DoorOpenState_2
    btfss OnPushButton    ; ignore
    bra DoorOpenState_3
    call DoBeep
    call DoorOpenState_leave
    bra DoorOpenState
DoorOpenState_3
DoorOpenState_end
    bra DoorOpenState_begin
DoorOpenState_leave
    call DoDong
    return
HeatingState
    call DoStartHeater
    call DoStartCookTimer
HeatingState_begin
    call sleepAndWaitEvents
HeatingState_0
    btfss OnPushButton    ; stop
    bra HeatingState_1
    call HeatingState_leave
    bra WaitingState
HeatingState_1
    btfss OnDoorOpen    ; open
    bra HeatingState_2
    call HeatingState_leave
    bra DoorOpenState
HeatingState_2
    btfss OnCookTimerExpired    ; timer
    bra HeatingState_3
    call HeatingState_leave
    bra WaitingState
HeatingState_3
HeatingState_end
    bra HeatingState_begin
HeatingState_leave
    call DoStopHeater
    call DoSuspendCookTimer
    return
WaitingState
WaitingState_begin
    call sleepAndWaitEvents
WaitingState_0
    btfss OnPushButton    ; start
    bra WaitingState_1
    btfss IfTimerIsSet
    bra WaitingState_1
    bra HeatingState
WaitingState_1
    btfss OnDoorOpen    ; open
    bra WaitingState_2
    bra DoorOpenState
WaitingState_2
    btfss OnPushButton    ; beep
    bra WaitingState_3
    btfss IfTimerIsNotSet
    bra WaitingState_3
    call DoBeep
    bra WaitingState
WaitingState_3
WaitingState_end
    bra WaitingState_begin

Figure 2

Extending state charts

Now, lets image that we have this microwave automaton in full production, and R&D department came up with a innovative and conceptual design of a microwave with two buttons and sales department insisted on adding a ‘polite reminder’ feature. State chart for the new microwave automaton is given on Figure 2 where blue color indicates new state and transitions and red cross denotes transition no longer needed. A big part of the state chart remains the same as in previous version one and, thus, can be reused in a new state chart. With the approach that this article suggests, a state chart can be extended by means of Java inheritance, e.g. new state chart extends the previous. With very little efforts the new automaton is defined as given below.

/**
 * State machine of a microwave oven with two buttons and polite reminder feature:
 * when cooked and door was not open - beep every N seconds during M minutes
 */
public class ModernMicrowaveStateMachine extends MicrowaveStateMachine {
	  /**
	   * This machine introduces several new events and actions
	   */
	  interface OnPushStopButton extends Event {}
	  interface OnPoliteBeepTimer extends Event {}
	  interface OnPoliteOffTimer extends Event {}
	  interface DoStartPoliteBeepTimer extends Action {}
	  interface DoStopPoliteBeepTimer extends Action {}
	  interface DoStartPoliteOffTimer extends Action {}
	  interface DoStopPoliteOffTimer extends Action {}
	  interface DoAddOneMinuteCookTimer extends Action {}

	  /**
	   * Alter the inherited Heating State
	   */
	  interface HeatingState extends MicrowaveStateMachine.HeatingState {
		  HeatingState	add		(OnPushButton e, DoAddOneMinuteCookTimer a);  // add one minute to the timer when push button is pressed
		  @Disable
		  WaitingState	timer	(OnCookTimerExpired e);					// disable this transition inherited from the old MW
		  CookedState   cooked	(OnCookTimerExpired e);					// introduce new transition on Timer Expired Event transit to CookedState State
		  WaitingState  stop	(OnPushStopButton e);					// on Push Stop Button Event transit to WaitingState State
		  @Disable
		  WaitingState  stop	(OnPushButton e);						// disable this transition inherited from the old MW
	  }
	  /**
	   * Add new state to provide polite beep reminder
	   */
	  interface CookedState extends State {
		  @OnEnter void onEnter	(DoStartPoliteBeepTimer a, DoStartPoliteOffTimer b ); // on enter start timers Polite Beep and Polite Off
		  DoorOpenState stop	(OnDoorOpen e);							// on Door Open Event transit to Door Open State
		  HeatingState  start1	(OnPushButton e, IfTimerIsNotSet i, DoAddOneMinuteCookTimer t); // on Push Button Event transit to WaitingState State
		  HeatingState  start	(OnPushButton e, IfTimerIsSet i);  		// on Push Button Event transit to WaitingState State
		  WaitingState  stop	(OnPushStopButton e); 					// on Push Stop Button Event transit to WaitingState State
		  WaitingState  idle	(OnPoliteOffTimer e); 					// stop beeping after M minutes
		  CookedState   beep	(OnPoliteBeepTimer e); 					// beep every N seconds
		  @OnLeave void onleave	(DoStopPoliteBeepTimer a, DoStopPoliteOffTimer b ); 	// on leave stop timers
	  }
}

There is one new annotation added: @Disabled. It is used to indicate a deletion of unused links that were inherited from the original chart. Output for this automaton is following

;-----------------------------------------------------
CookedState
    call DoStartPoliteBeepTimer
    call DoStartPoliteOffTimer
CookedState_begin
    call sleepAndWaitEvents
CookedState_0
    btfss OnPushButton    ; start
    bra CookedState_1
    btfss IfTimerIsSet
    bra CookedState_1
    call CookedState_leave
    bra HeatingState
CookedState_1
    btfss OnPushStopButton    ; stop
    bra CookedState_2
    call CookedState_leave
    bra WaitingState
CookedState_2
    btfss OnDoorOpen    ; stop
    bra CookedState_3
    call CookedState_leave
    bra DoorOpenState
CookedState_3
    btfss OnPoliteOffTimer    ; idle
    bra CookedState_4
    call CookedState_leave
    bra WaitingState
CookedState_4
    btfss OnPoliteBeepTimer    ; beep
    bra CookedState_5
    call CookedState_leave
    bra CookedState
CookedState_5
    btfss OnPushButton    ; start1
    bra CookedState_6
    btfss IfTimerIsNotSet
    bra CookedState_6
    call DoAddOneMinuteCookTimer
    call CookedState_leave
    bra HeatingState
CookedState_6
CookedState_end
    bra CookedState_begin
CookedState_leave
    call DoStopPoliteBeepTimer
    call DoStopPoliteOffTimer
    return
HeatingState
    call DoStartHeater
    call DoStartCookTimer
HeatingState_begin
    call sleepAndWaitEvents
HeatingState_0
    btfss OnPushButton    ; add
    bra HeatingState_1
    call DoAddOneMinuteCookTimer
    call HeatingState_leave
    bra HeatingState
HeatingState_1
    btfss OnPushStopButton    ; stop
    bra HeatingState_2
    call HeatingState_leave
    bra WaitingState
HeatingState_2
    btfss OnCookTimerExpired    ; cooked
    bra HeatingState_3
    call HeatingState_leave
    bra CookedState
HeatingState_3
HeatingState_end
    bra HeatingState_begin
HeatingState_leave
    call DoStopHeater
    call DoSuspendCookTimer
    return
DoorOpenState
    call DoDing
DoorOpenState_begin
    call sleepAndWaitEvents
DoorOpenState_0
    btfss OnDoorClose    ; resume
    bra DoorOpenState_1
    btfss IfTimerIsNotSet
    bra DoorOpenState_1
    call DoorOpenState_leave
    bra HeatingState
DoorOpenState_1
    btfss OnDoorClose    ; idle
    bra DoorOpenState_2
    btfss IfTimerIsSet
    bra DoorOpenState_2
    call DoorOpenState_leave
    bra WaitingState
DoorOpenState_2
    btfss OnPushButton    ; ignore
    bra DoorOpenState_3
    call DoBeep
    call DoorOpenState_leave
    bra DoorOpenState
DoorOpenState_3
DoorOpenState_end
    bra DoorOpenState_begin
DoorOpenState_leave
    call DoDong
    return
WaitingState
WaitingState_begin
    call sleepAndWaitEvents
WaitingState_0
    btfss OnPushButton    ; start
    bra WaitingState_1
    btfss IfTimerIsSet
    bra WaitingState_1
    bra HeatingState
WaitingState_1
    btfss OnDoorOpen    ; open
    bra WaitingState_2
    bra DoorOpenState
WaitingState_2
    btfss OnPushButton    ; beep
    bra WaitingState_3
    btfss IfTimerIsNotSet
    bra WaitingState_3
    call DoBeep
    bra WaitingState
WaitingState_3
WaitingState_end
    bra WaitingState_begin

Representing other graph and tree-alike structures

Although, this article is focused on finite state automatons, similar approach can be applied for defining other kind of graphs and trees. The author has a proof of concept for using nested classes as a representation of a web-application URI structure and mapping HTTP requests issued by very complex but strictly structured HTML forms.

Attachments

FSA-Sources

public class SQLpeople {
  public static final String sqlSELECTall = Comments.load();
  /*--
    SELECT * FROM people;
    --*/
}

To make it available at run-time, this source file should be packaged together with the class file. That’s everything you need to make SQL statements loaded…
Well, almost everything . One minor thing left is an implementation of Comments.load(). You may implement it in your own or download from SourceForge an open source implementation (under LGPLv3 license).

Dialectism

If your application is designed to run with different DBMS engines, maintaining SQL in different dialects may become a challenge. The Comments class proposes a solution as illustrated below:

public class SQLpeople {
  public static final String sqlSELECTtopN = Comments.load(getCurrentDBMS());
  /*--
    --: pgsql
    SELECT * FROM people LIMIT ?;
    --: mssql
    SELECT TOP ? * FROM people;
    --*/
}

Where getCurrentDBMS() is your static function that returns name of the current DBMS, and --: pgsql and --: mssql are discriminator values designating statements appropriate for different DBMS.

How it works

The Comments class just a friendly decorator created for the sake of convenience. Its method load() uses StackFrame to gather information about invocation point and passes name of the source file, line number (N), and class name to the CommentRetriever.retrieve(), which opens the source file as a resource stream, skips N lines, reads content until it finds --*/ in the line and then uses regex to extract content between /*-- and --*/. If the discriminator parameter is null, retrieve returns extracted content. Otherwise it finds designators --: <discriminator> and tests its equity against the parameter. If they are equal method returns content of the section between the current discriminator and the next one or end of the block. If block contains no discriminator equal to the parameter, it returns content before the first discriminator, unless default values are disabled by NODEFAULTS option.
That’s all you need to start using this class, for advanced topics please refer to Java docs.

Guidelines on authoring comments

There should be no characters between the end of the load() line and sequence /*-- that opens the block, except, of course, white spaces (space, tab, new line).

public class SQLpeople {
  /*
   * allowed comment
   */

  public static final String sqlSELECTall = Comments.load(); -- allowed comment

  /* disallowed comment */
  /*--
    SELECT * FROM people;
    --*/

}

Discriminator takes entire line, there should be no other text in this line

Errors

By default error messages are returned as output value and prepended with "--", are returned as the result of load() method. Although, this behavior can be opted (see Java docs for details).

A dimmer is an electronic device that controls alternate voltage applied to a lamp through delivering a selected portion of the mains sinusoid. Engineer, designing a dimmer needs to estimate how big this portion should be to get a desired luminance level. This article uses a model of incandescent lamp, tungsten resistivity, and human eye spectral efficiency to derive dependency of produced luminous flux over the voltage, gives a simple analytical function that describes this dependency with good accuracy (±2% comparing to the model).

Download PDF version of this article

Structured Abstract

Definitions

Process of controlling some output value (such as voltage U or luminous flux L) we will denote as a control function , defined on the control parameter :

(1)

Each of  monotonously increase on the defined range. Control functions defined on a different (other than ) argument we will denote in this article as .

Commonly used are linear () and logarithmic () control functions. To implement a desired control function , we needs to know what is  dependency. 
The following chapters give an attempt to derive  using a model suggested in (Agraval 1996).

Incandescent Lamp Model

An incandescent lamp is characterized with few nominal values: P_N – power consumption, U_N – nominal voltage, L_N – nominal luminous flux, produced by the lamp at nominal voltage. The flux is produced by filament, incandesced to nominal working temperature T_N.
When lower voltage U<U_N is applied, operating temperature T of filament is lower T_N and therefore it produces less luminosity L.

Filament Resistance

Power, consumed by a lamp, is expressed with Ohm low:

(2)

where  defines dependency of filament resistance over the temperature relatively to its nominal resistance R_N, which can be evaluated via P_N and U_N:

(3)

Dependency  for tungsten is not linear in the working range of temperatures (1000-2500K). For this model we will use polynomial approximation of tungsten resistance ρ, [Harang 2003]:

(4)

 can be expressed via  as the following:

(5)

Filament Temperature

During operation, filament radiates electromagnetic energy and dissipates heat via conduction and convection. To estimate radiation, filament is modeled [Agraval 1996] as a simple non-ideal blackbody that obeys Plank’s radiation law:

(6)

where  is power radiated between wavelength  and ,  - tungsten emittance, and A is filament area. The total power emitted over all wavelengths is:

(7)

where σ is the Stefan-Boltzman constant and  is average emittance over all wavelengths, which is approximated as a second order polynomial (Harang 2003):

(8)

In a steady-state operation, power applied to the lamp is in balance with power radiated and dissipated to outside ambient. Dissipation has two constituents – conduction and convection. Agraval in [Agraval 1996] has suggested a reasonable way of accounting dissipation as a factor of input power:

(9)

Solving (8) for P:

(10)

Substituting left side of (10) with right side of (2):

(11)

Using (11), we may derive :

(12)

Figure 1 illustrates dependency

Figure 1. Dependency of T on fraction of applied voltage ξ_U for different T_N

Luminance

Not all power radiated by filament has its effect on luminous flux. Some of the energy is absorbed by bulb glass and dissipated as heat. Although, this absorption depends on λ, we will simplify this absorption to a constant factor η<1.

Major part of the emitted energy is not visible to human eye. This is described as spectral efficiency function S(λ), approximated as the following [Agraval 1996]:

(13)

Thus, total luminous flux produced by a lamp can be defined as:

(14)

where

(15)

Thereby, control function  can be expressed as a function of T:

(16)

For working range of temperatures and visible area, emissivity є(λ,T) can be approximated as the following [Larrabee 1957]:

(17)

where T is in °K and λ in nm. Substituting (17) in (16) and integrating numerically (16) we get dependency, shown on Figure 2:

Figure 2. Dependency ξ_L(T) for different T_N

Solving Luminance vs. Voltage

Using T as a parametric variable, we may numerically compute (11), (15) and graphically solve dependency ξ_L(ξ_U), as shown on Figure 3:

Figure 3. Dependency ξ_L(ξ_U) for different T_N

As Figure 3 indicates, ξ_L(ξ_U) is affected by a design factor – nominal temperature T_N.

Approximation

Figure 4. Dependency ξ_L(ξ_U³)

As it appears (see Figure 4), dependency ξ_L(ξ_U³) looks quite linear for ξ_U³>0.2 and has some higher-order dependency for ξ_U³<0.2. Therefore we will try approximating ξ_L(ξ_U) as two polynoms:

(18)

Value ξ_Lat x=1 is equal to 1 by nature of ξ, therefore c can be expressed via k:

(19)

To solve a and x₀ we will require continuality of  and its derived function , this gives us two equations with three unknowns:

(20)

Solving (20) for a and x₀ we get them expressed via k:

(21)

Thereby,  depends on a single constant k, which is then wiggled around to find a value giving lowest RMS deviation . Table 1 lists selected values for few most common nominal temperatures T_N, Figure 5 illustrates this dependency, and Figure 6 shows modeled curves and values, approximated with (20).

Table 1. k values for some T_N

Figure 5. k variations over T_N

Figure 6. Modeled curves and approximated values (marks)

Since designer of a dimmer may not exactly know nominal temperature of the dimmed lamp, kcan be selected for an average nominal temperature. Suggested value k=1.05 gives ±2% error (against the model) for T_N in range 2800-3100 °K. For this k, equation (20) becomes practically concrete:

(22)

Sine Wave Dimmer

A sine wave dimmer implemented with pulse-width modulation controls applied voltage with a cycle duty, which we will denote as control function ξ_t. Modulation frequency is usually chosen much higher than mains frequency. Therefore, RMS of output voltage is proportional to cycle duty, and control function ξ_U as simple as:

(23)

To make ξ_L(p), linear on parameter p, function ξ_t(p) should be defined as the following:

(24)

Applying (24) to equation (22) we get

(25)

Phase Control Dimmer

When implementing an AC dimmer based on phase control technique, one needs to tabulate cycle duty values ti as a function of desired luminance level pi. 
Following the same approach, we introduce control function ξ_t:

(26)

where t is cycle duty (time when the switch is on) and tM is the mains half period, and f is the mains frequency. Average power  applied to the lamp, can be evaluated as the following:

(27)

where UA is voltage amplitude. Integrating (27) we can define ξ_P as the following

(28)

Considering that , and substituting (28) to (22) we may estimate .

Figure 7. Dimmer control functions ξ_L and ξ_U

Applying approach used in (24) function ξ_t(p) is defined as following:

(29)

Although, reverse function of (28) is not solvable analytically, it can be solved numerically.

Conclusions

As a result of numerical modeling, the following approximation functions are suggested:

• Estimation of produced luminous flux over the voltage:

L = L0 * ((U/U0 < 0.575) ? 1.369 * (U/U0) ^ 4 : (1.05 * (U/U0) ^ 3 - 0.05);

• Tabulation of cycle duty over the control parameter p

t = (p < 0.1496) ? (0.925 * (p) ^ -4) : (0.984 * (p + 0.05) ^ -3);

References

Agraval D.C., Leff H.S., Monon V.J. (1996)
"Efficiency and efficacy of incandescent lamps"
American Journal of Physics, May 1996, Volume 64, Issue 5, pp. 649-654
http://scitation.aip.org/getabs/servlet/GetabsServlet?prog=normal&id=AJPIAS000064000005000649000001&idtype=cvips&gifs=yes

Harang O., Kosch M. J. (2003) "Absolute Optical Calibration Using a Simple Tungsten
Bulb"
Sodankylä Geophysical Observatory Publications, 2003, pp. 92:121-123
http://spaceweb.oulu.fi/28AM/proc_papers/27_harang_et_al_calibration_with_tungsten_bulb.pdf

Larrabee R.D. (1957) "The spectral emissivity and optical properties of tungsten"

Research Laboratory Of Electronics, Massachusetts Institute of Technology
http://dspace.mit.edu/bitstream/1721.1/4755/1/RLE-TR-328-04734719.pdf

(Note: In ErWin 7.3 templates look very different from 7.2, but nevertheless, I believe, similar approach still can be applied).

Trick 1. Use Oracle 10.x as the target DBMS

PostgreSQL has common ideology with Oracle and, in my opinion, is the best choice for PostgreSQL needs.

Trick 2. Fix syntax differences
I have encoundered two syntax differences – in the order designator in the column specifier of CREATE INDEX statement and extra parenthesis in ALTER TABLE ADD CONSTRAINT

Following samples illustrate what causes PostgreSQL to fail with generated code:

CREATE INDEX Publisher_xIF1 ON Publisher (PublisherID ASC);

ALTER TABLE Publisher
ADD (CONSTRAINT Publisher_fObject FOREIGN KEY (ObjectID) REFERENCES Object(ObjectID) ON DELETE CASCADE);

This can be fixed by altering ErWin FE template as the following:

2.1. Copy and rename Oracle.erwin_fe_template to Postgre.erwin_fe_template and then open it in a text editor.

2.2. Find SPItemBegin = KeyGroupMembers 2.3. Below that find and remove line containing [" " PropertyValueX("Key Group Sort Order")]
2.4. Find"ADD " "(" IsNotNullX(ExecuteX("FKConstraint"),"") ")" 2.5. Remove "(" ")", so it looks like the following:"ADD " IsNotNullX(ExecuteX("FKConstraint"),"") 2.6. Switch you project to use this template (Tools>Forward Engineer>Scema Generation; Database template – Browse; select Postgre.erwin_fe_template) These two tricks are essential to produce valid SQL code from an ErWin model that contain no Oracle specific features, like table partitions, logging, validation, etc. If you already have an Oracle model which you prefer to keep intact and still be able to generate SQL for Postgress, you will need to void all parts of FE template responsible for Oracle specific features.
Trick 3. Implement use of INHERITS for subtype relationships This part is optional and necessary if you really need to use table inheritance. 3.1. Find first occurrence of [ExecuteX("EndOfStatementX")] after SPItemBegin = Create Entity
3.2. Add [ExecuteX("Extra Properties")] before [ExecuteX("EndOfStatementX")] [ExecuteX("Table Properties")] [ExecuteX("Extra Properties")] [ExecuteX("EndOfStatementX")]
3.3. At the end of the file add
SPItemBegin = Extra Properties 10000: {# ForEachVectorReferenceX("Child Relations Ref") { [ IsPropertyEqual("Type","9") " INHERITS(" [ PushReferenceX("Parent Entity Ref") [ [OwnerX"."]PhysicalNameX ] PopX ] ")" ] } #} SPItemEnd

Read more about SISAM – SImple SAMpler and SISAN – SImlpe Signal Analyse

Example3 – Designing MIHA – Multi Input Hall Automaton

Introduction

There are two common approaches for light switching in halls and staircases – off-timers and intermediate switching schemes (please excuse me if terminology is wrong). Off timers turn light on when user pushes a button and turn off when specified time elapsed. Intermediate switching schemes toggle lights when user toggles any switch (of two). Each approach has its own advantages and disadvantages, however, both approaches require special switches, which could be an undesired constraint for interior design. See, for example, Intermediate lighting switch, Stair case timer, Multifunction staircase timer

Requirements (user’s needs)

Implement a light-control appliance that:

• combines off-timer and intermediate switchers
• provides support for at least 3 switches
• supports regular light switches as well as push-buttons
• provides settable 0.5-10 min timer range with a simple user interface for entering value

MIHA Design Description

Key Design Decisions:

• Implement the appliance (named MIHA) as a VELOOS application running on a PIC microcontroller
• Store application configuration in EEPROM during device programming
• Use potentiometer for specifying timeout

Architecture
MIHA consists of the following units (see architecture diagram on Figure 1):

Mapping Architecture to Implementation. Mapping from architectural units to implementation units is straightforward – all MIHA units are directly mapped to operating system objects, inter-unit communications are mapped to messaging. All MIHA objects are configurable with EEPROM data. To make design flexible, object configuration embeds acceptor handle. The latter two decisions establish a generality which is captured as two abstract classes: PDO – a configurable Process Data Object PDD – a dynamically bound PDO (See class diagram on Figure 2)		Figure 1.
		Figure 2.

Moduling

Major advantage provided by VELOOS is ability to design and implement loosely coupled objects. The following practice can be applied to get full advantage of loose coupling:

• A unit should be made up of (at least) two files: (1) .inc containing interface and (2) .asm – implementation
• Each unit should implement one class or a hierarchy of closely related classes.
• A unit should not instantiate objects of reenterable or configurable classes. Instead it should publish class name in the interface.
• A unit may instantiate object of a non-reenterable class. In this case it should publish object name and encapsulate class name.

Sharing RAM among objects

Decoupling objects via messaging mechanism provides a very explicit and straightforward watershed for scoping variables – everything that should survive between two messages is a part of object state and should be allocated in udata section, everything that may be discarded after handling the message is a temporary variable and can be allocated in udata_ovr section.

Using Timer for Resource Access Arbitration

Class Potentiometer Parameter Input (PPI) implements time-quantified approach for sharing ADC among several instances – time is sliced on N quants, each instance may access hardware only if TIME mod N equals to channel number. To simplify computing TIME mod N, N can be chosen as power of 2. In this example N = 16.

Multi-input Debouncer On timer event Debouncer polls the port three times in a row and applies majority logic to determine current switch state. This approach eliminates sporadic spikes than may be present in a noisy environment. For each assigned pin it maintains a counter. This counter is incremented whenever pin level is high and decremented if low. Counter is maintained in range 0..16, e.g. when it reaches the boundary it is not changed. When counter reaches upper threshold (12) logical output state is changed to 1 and to 0 when it reaches lower threshold. This is a software model of an RC-integration connected to a Schmidt trigger. Few samples of switch bouncing are shown on figures on right. The switches are regular light switches manufactured by VIKO. Hardware Schematic MIHA schematic is shown on Figure 6. Relay, loaded on PIC12, should have actuating current up to 25 mA. Resistors R1-R4 are used for pull-up and can be roughly 1 kOhm. In an environment with strong EMI their can be reduced to avoid pickup. Package Content The package includes three projects to build this application for three different devices – PIC12F675, PIC16F690, PIC18F248. It is licensed to public under the Open Software License Download MIHA Sources v.1.0		Figure 3.
		Figure 4.
		Figure 5.
		Figure 6.

Actuators and Generators are implemented as instances of Actuator and Generator classes. Yet another class in this example protocol driver parses the incoming via software USART commands and forwards it to a corresponding object. Command format is: command[data,[data]]; COM port settings: 2400, 8bit no parity, 1 stop bits.
USART is implemented in software and uses INT0 and TMR1 interrupts for timing bits.
Command language consist of 8 commands (H..O)

• H,I,J control an actuator,
• K,L control a generator,
• N all actuators do OFF, susped all generators
• O all actuators do ON, resume all generators.

H,I,J commands accepts ‘0′ and ‘1′ as a parameter to execute OFF or ON command respectively. K,L commands should be supplied with pulse and pause duration

For example:

• H0 Actuator 1 do OFF
• LUA Turn on generator 1 with 85 ms pulse and 65 ms space

Example 3 Sources

Hardware Scematics. Connect loads to GP0,GP1,GP4,GP5 (not shown on the schematic)

Simulation Results

Download VELOOS v.1.0

Supporting other 14-bit core and 16-bit core devices

By design, VELOOS allocates its message at the end of available banked (e.g. not shared) memory. Unfortunately, standard .inc does not include constants defining memory limits, therefore pic.inc refines “device model” and this refinement block has to be provided for each device to be used for a VELOOS application.


 ifdef __16F690
  include "p16f690.inc"
  include "pic16.inc"
  _pic           = _pic16F690
  _pic_maxram    = 016Fh ; with shared bank excluded
  _pic_maxrom    = 0FFFh
  _pic_maxeeprom = 0FFh
 endif


With this refinement, VELOOS is expected to work for any 16-bit core devices (PIC18), and any 14-bit core (most of PIC14 and some of PIC12). Perhaps, it may also work on 12-bit core (PIC10 and some of PIC12). However, since there are no interrupts, timer drivers can not be used. Also, these devices have severe memory constraints, which make use of OS unreasonable.

Example2 – Heartbeat Driven PDO

Design Description

This sample application implements two PDO each triggering port pin with a certain period: first PDO is on 1 sec period, second – on 1 ms. Since behavioral pattern of these PDO are the same, they were implemented as instances of the same class.

Deploying VELOOS Timer Driver

Timer Driver is a non-reenterable encapsulated PDO with an interrupt handler and internal counters for millisecond and seconds. To deploy a timer driver to VELOOS application, the project should include file vtm0.asm (Timer0 based) or vtm2.asm (Timer2 based). Timer constants are calculated automatically based on _osc_clock. Timer driver configures hardware timer for 1 ms interrupts. When a timer interrupts occurs, Interrupt Handler sends a broadcast message. Timer PDO counts 1ms messages and on every 1000-th broadcasts a 1s message. Both 1 ms and 1 s messages include current time value.

In a pseudo language messages can be declared as the following (acceptor field is not shown):

Handling Timer Messages

Timer messages are regular VELOOS messages. To handle a timer message, PDO should first recognize the message and then, if necessary, examine time delivered with the message and take appropriate action:

MyHandler                                   ; FSR points to message ID field
    movlw       VTMR_cMsgIDTimer1ms
    xorwf       INDF, W                     ; if message.msg_id <> VTMR_cMsgIDTimer1ms
    skpz
    return                                  ; return
    incf        FSR, F                      ; make FSR pointing to LSB of message data
    movf        INDF, W
    andlw       0F0h
    xorlw       007h                        ; on 7-th msec of every 16 msec
    skpnz
    return
    ; do something


Targeting Reenterability

To make a class reenterable, it should not be build-time-bound to any resource. This sample class achieves reenterability by using This as a pointer to EEPROM data with configuration (message ID, port mask) assigned to a particular class instance. In run-time PDO reads data from EEPROM on per need basis (e.g. does not cache in in registers). Since message ID is also stored in EEPROM, message handler first reads message ID from EEPROM and then message is processed:

TmrHandler
    movf        This, W
    call        EE_read                     ; W = EEPROM[This]; //(== msgid)
    xorwf       INDF, W
    skpz
    return


With this design, class should be properly instantiated, e.g. object data should point to the configuration location in EEPROM. This can be achieved with use of a label, placed in EEPROM section:

DEEPROM code
On1mSecData                                 ; Configuration name
   de      VTMR_cMsgIDTimer1ms, .1          ; Configuration data
VOS_Objects                                 ; Object registry begins
On1mSec                                     ; Object name (not necessary for this example)
   VOS_mPersistentObject MyTimer, On1mSecData ; Instance on MyTimer constructed with
                                            ;object data pointing to configuration

Building the project

All classes and objects for this example (except Timer) are declared, implemented and instantiated in one file: main.asm. Although this is not a recommended practice, this example, for simplicity, gives it this way. Moduling aspects will be discussed in a subsequent example.

A package with sources for this example can be downloaded on this link. It includes the following files:

Download sources

Running the application This application was loaded to PIC16F690 on "Low Pin Count Demo Board" supplied with PICkit™ 2. Activity of 1s driven object can be visually monitored with a led. Activities of other objects (1ms and self-triggering) can be monitored aurally, for example by connecting a headset, or with a scope. Signals from RC2 and RC3 were captured with Simplescope and their traces are shown on Figure 1 and Figure 2. As results show, in the first run 1 ms period was actually shorter  – 970 us instead of 1000. Therefore, for the next run internal oscillator has been tuned with -4 value. Traces indicate that 1 ms period varies 1000-1080 ms – this is an expected effect of message queuing.		Figure 1
		Figure 2

Application Source

 
;      License:   Licensed to public under the Open Software License
;                http://www.opensource.org/licenses/osl-3.0.php
 include "pic.inc"
 include "vos.inc"
 
;------------------------------------------------------------------------------
 __CONFIG _WDT_ON & _INTRC_OSC_NOCLKOUT & _CP_OFF & _PWRTE_ON & _MCLRE_ON & _FCMEN_OFF & _BOR_OFF & _IESO_OFF
;------------------------------------------------------------------------------
 
 constant mask  = 02h                      ; mask to be used for driving port (RA1)
 constant msgid = 040h                     ; message ID
 constant mask1ms = 04h                    ; mask to be used for driving port on 1 msec event (RC2)
 constant mask1s  = 08h                    ; mask to be used for driving led (RC3)  
VOS_Classes                                ; Class definitions begin
MyClass VOS_mClass MyHandler, MyInit       ; MyClass implementes MyHandler and MyInit methods
MyTimer VOS_mClass TmrHandler, TmrInit     ; MyTimer implementes TmrHandler, TmrInit
                                           ; Class definitions end with beginning of the next code section
VOS_Objects                                ; Object registry begins
MyObject
  VOS_mPersistentObject MyClass, mask      ; Instance of MyClass constructed with object data == mask
On1mSec

  VOS_mPersistentObject MyTimer,On1mSecData; Instance on MyTimer constructed with object data pointing

                                           ; to EERPOM location
On1Sec
  VOS_mPersistentObject MyTimer,On1SecData ; Another instance on MyTimer
                                           ; Object registry ends with beginning of the code next section
;------------------------------------------------------------------------------

DEEPROM code
On1mSecData
  de VTMR_cMsgIDTimer1ms, mask1ms
On1SecData
  de VTMR_cMsgIDTimer1s, mask1s
;------------------------------------------------------------------------------
    code
MyInit                                     ; This was loaded with object data
    comf       This, W                     ; W := ~mask

    banksel    TRISA
    movwf      TRISA                       ; Prepare port for output
    VOS_mPostMessage MyObject, msgid       ; post message to itself
    return
;------------------------------------------------------------------------------
 
MyHandler                                  ; FSR points to message ID field, This is loaded with object data
    movlw       msgid
    xorwf       INDF, W                    ; if message.msg_id <> msgid
    skpz
    return                                 ; return
    movf        This, W
    banksel     PORTA
    xorwf       PORTA, F                   ; Toggle port
    VOS_mPostMessage MyObject, msgid       ; post message to itself
    return
;------------------------------------------------------------------------------

TmrInit
    incf        This, W
    call        EE_read                     ; W = EEPROM[This+1] == mask
    xorlw       0FFh                        ; W = ~mask
    banksel     TRISC
    andwf       TRISC, F                    ; Prepare port for output according to mask
    return
;------------------------------------------------------------------------------
 
VOS_BootHandlers code                       ; starts a section for the application boot handler
    banksel     ANSEL
    clrf        ANSEL                       ; Turn all pints to digital
    clrf        ANSELH
    banksel     OSCCON                      ; Set Fosc = 8Mhz
    movlw       (.7 << IRCF0)
    movwf       OSCCON
    banksel     OSCTUNE
    movlw       -.4
    movwf       OSCTUNE
    ; !!! NO RETURN ALLOWED !!!
;------------------------------------------------------------------------------
 
 end