[download] Module: Newscaster - announces scheduled events.

123

Senior Member
index.php
File Name: Module: Newscaster - announces scheduled events.
File Submitter: 123
File Submitted: 16 Jun 2010
File Updated: 16 Jun 2010
File Category: Premise
Author: 123
Contact: PM me
Version: 1.4

Newscaster is a Module that displays and announces scheduled events.


How it works
Three times a day, it scans a list of user-defined "NewsEvents", selects the events that occur on the current day ("NewsBulletins") and assembles them into a speech-friendly "Newscast". It proceeds to speak the Newscast, via Text-To-Speech, and displays it in Premise Browser.

NewsEvents are defined, and modified, with Builder and appear in the Media > Newscaster folder. Premise Browser can be used to view existing NewsEvents but not to create new events or modify existing ones. The current version of Newscaster does not support MiniBrowser.


What's in a NewsEvent?
A NewsEvent's message can be customized using Message Variables. For example, if you were married on August 8th, 2000 then, on August 8th, 2010 the following message:
"Our {years!} wedding anniversary."
will be announced as
"Our tenth wedding anniversary."
A NewsEvent's message can also contain an evaluated expression such as [Home.PorchLight.PowerState=true] which turns on the PorchLight.

Each NewsEvent has a simple schedule (described below) and the following additional properties:
Category
Indicates the type of event (Anniversary/Appointment/Astronomical/Birthday/Holiday/Task/Vacation/Weather). Newscaster uses this to group NewsEvents when announcing them: "There are three Task bulletins.".

Channel
Indicates if the event will be spoken, displayed, or both. (All/Voice/Text)

Enabled
Indicates if the event is active (True/False). This is a convenience feature and allows you temporarily suspend prcessing of one or more News Events.

Reminder
Indicates if the event should be announced prior to its actual date as a form or reminder (None/1/1_3/1_3_5/...). For example "1_3_5" means announce a reminder one, three, and five days prior to the actual event date. This is useful when you must receive advance notice of an event. Newscaster will also prepend a reminder phrase before announcing the News Event's messsage. For example, "Reminder. In 3 days, Our tenth wedding anniversary."

Period
Indicates when the event should be announced during the day (All/Morning/Afternoon/Evening). Some News Events need to be announced in the morning and at no other time of the day. For example, "Take out the trash." is useful on the Morning of trash day, when trash collection occurs, but not in the Afternoon or Evening.

RefDate
Indicates the event's actual date and is used as a reference when calculating elapsed time. Whereas an event's schedule indicates when to announce the event (i.e. every August 8th), its RefDate indicates the event's original date (i.e. August 8, 2000).


How do you schedule a NewsEvent?
A NewsEvent may occur once or periodically. The following fields define its schedule (values are shown in parentheses):
Year (All)
Month (All)
Day (All)
Monday (True)
Tuesday (True)
Wednesday (True)
Thursday (True)
Friday (True)
Saturday (True)
Sunday (True)
If you leave the default values untouched, the event will occur every day for all months in all years.

The following schedule indicates the event will be announced on August 8th of every year:
Year (All)
Month (August)
Day (8)
Monday (True)
Tuesday (True)
Wednesday (True)
Thursday (True)
Friday (True)
Saturday (True)
Sunday (True)

The following schedule indicates the event will be announced every Thursday in 2010:
Year (2010)
Month (All)
Day (All)
Monday (False)
Tuesday (False)
Wednesday (False)
Thursday (True)
Friday (False
Saturday (False)
Sunday (False)

The fields behave like filters and let you specify any combination including nonsensical ones. For example, if you disable all days except Monday and then indicate Day = 12, then the event will occur on the rare occasion when the twelfth of the month is also a Monday. Similarly, if you set Day = 31 and Month = February then the event will never occur because February does not have a 31st day.


What's a Message Variable?
Variables within an event's message can be used to customize the message. Variables can be used to calculate elapsed time (using RefDate as the starting date) or the current date. The format of a variable is simply a Keyword and a Type delimited by braces: {<KEYWORD><TYPE>}. There are eleven Keywords and each one has two Types.
Examples:
{years#}
{years!}
{woy#}
{woy!}
A keyword can be one of two types, numeric or ordinal, where numeric is indicated by the pound character (#) and ordinal using the exclamation mark (!). For example, {years#} means to display the elapsed years as a number (i.e. 7) and {years!} means to display it as an ordinal position (i.e. seventh). Week-of-Year is expressed as a numeric value using {woy#} and as an ordinal position with {woy#}.

Keywords
  • years
  • months
  • weeks
  • days
  • year
  • month
  • week
  • day
  • time
  • woy
  • doy

Types
  • Numeric: #
  • Ordinal: !

The following list describes all eleven Keywords.

Elapsed years
{years#}
{years!}
Examples:
Today is Bill's {years!} birthday. -> Today is Bill's sixth birthday.
Bill is {years#} years old today. -> Bill is 6 years old today.

Elapsed months
{months#}
{months!}
Examples:
{months!} payment of the car lease is due. -> Eighteenth payment of the car lease is due.
Lease payment number {months#} of 36 is due. -> Lease payment number 18 of 36 is due.

Elapsed weeks
{weeks#}
{weeks!}

Elapsed days
{days#}
{days!}

Current year
{year#}
{year!}

Current month of the year
{month#}
{month!}

Current week of the month
{week#}
{week!}

Current day of the month
{day#}
{day!}

Current time of the day
Numeric format is: 7:00 PM
Ordinal format is: 19:00
{time!}
{time#}

Current week of the year - elapsed
{woy#}
{woy!}

Current day of the year - elapsed
{doy#}
{doy!}
Examples:
Today is day {doy#}. -> Today is day 65.
Today is the {doy!} day of the year. -> Today is the sixty-fifth day of the year.

As mentioned, a NewsEvent's message can include an 'evaluated expression' containing Premise script. An 'evaluated expression' can be used to change a Home object's properties or run an existing GlobalScript. Whereas a variable uses braces {}, an evaluated expression is delimited by brackets [].

Evaluated expression
[]
Examples:
Take out the trash this morning. [Home.Exterior.Pathlights.Powerstate=true]
Today is EarthDay.[gRunEarthDaySchedule]


Installation
  1. Copy Newscaster.gif and Newsevent.gif to C:\Program Files\Premise\SYS\web\Images\ClassImages.
  2. Using Builder, import the XDO file. Two new Modules will be added: Global and Newscaster.
  3. In Builder's Shortcut bar, click Modules.
  4. Move the two Modules (drag 'n drop) so that they are positioned higher in the treeview than the Plugins module.
  5. In the Explorer window, navigate to Modules > Newscaster > Macros > Newscaster > Initialize
  6. Run the Initialize macro by momentarily enabling its Trigger property (in the Properties window). This step will create Media > Newscaster folder and populate it with one NewsEvent called "HappyNewYear".
  7. In Builder's Shortcut bar, click Home.
  8. In the Explorer window, right-click Home and select New > Newscaster.


Configuration
The following timer: Modules > Newscaster > Timers > UpdateNewsBulletins will fire at 1:00 AM, 6:00 AM, 12:00 PM, and 6:00 PM. Its OnChangeTrigger script looks for the Home.Newscaster object and triggers its "Update" property. In other words, it periodically makes Newscaster review all existing NewsEvents (found in the Media > Newscaster folder), select the ones that occur today (referred to as NewsBulletins), and combines the NewsBulletins into a form (called a Newscast) that is suitable for Text-To-Speech (TTS). The NewsBulletins are visible in Premise Browser. If you have created the Newcaster object somewhere else (i.e. not in Home.Newscaster) or renamed it, then you will have to customize the contents of OnChangeTrigger.

The following timer: Modules > Newscaster > Timers > Newscaster fires at 6:46 AM and its OnChangeTrigger script speaks the current Newscast via an Audrey driver. You will need to modify this script to work with your Text-To-Speech (TTS) driver. If you have no plans to use TTS, you can safely disable (or delete) this Timer.


Usage
How to create a NewsEvent
  1. In Builder's Shortcut bar, click Media.
  2. In the Explorer window, navigate to Media > Newscaster
  3. Right-click Newscaster and select New > NewsEvent
  4. In Name, supply a compact name for the event.
  5. In Display Name, supply a descriptive name for the event.
  6. In Description, enter the event's message and any required Message Variables or Evaluated Expressions.
  7. If you have added a Message Variable that calculates elapsed time, you must provide a reference date; set RefDate to the event's date.
  8. Select an appropriate Category, Channel, and Period for the event.
  9. If you want Newscaster to remind you prior to the event's date, set Reminder to a suitable reminder cycle (i.e. "1_2" means 1 and 2 days before the event).
  10. Set the event's schedule using an appropriate combination of Year, Month, Day, etc.

NewsEvent Properties
Category: Anniversary/Appointment/Astronomical/Birthday/Holiday/Task/Vacation/Weather
Channel: All/Voice/Text
Enabled: True/False
Year: All/2008/2009/...
Month: All/January/February/March/...
Day: All/1/2/3/...
Reminder: None/1/1_3/1_3_5/...
Monday: True/False
Tuesday: True/False
Wednesday: True/False
Thursday: True/False
Friday: True/False
Saturday: True/False
Sunday: True/False
Period: All/Morning/Afternoon/Evening
RefDate: MM/DD/YYYY
DaysToEvent: (read-only; only applicable if the event's message contains a variable for elapsed time; indicates number of days remaining before event occurs; "-1" is displayed if the event does not have a valid message variable)

How Newscaster handles Weather
Create a NewsEvent called "DailyWeather" and set its category to "Weather". "DailyWeather" is an empty vessel that is filled with a new message each time Newscaster composes a fresh Newscast.

Newscaster's "UpdateCustomBulletins" (Modules > Newscaster > Classes > Newscaster > UpdateCustomBulletins) is a method that is executed each time a new Newscast is composed. It contains code to get weather data and place it into DailyWeather's message.

The current version of Newscaster's UpdateCustomBulletins contains code that acquires weather data from the EnvironmentCanada and WeatherStationPWS modules. If you use these modules, you simply need to alter the code so that it points to the proper Home objects. If you do not use these modules, you will need to modify the code so that it acquires it from your weather module(s).

Click here to download this file
 
Top