INSTEON Developer's Guide
INSTEON Developer's Guide
INSTEON Developer's Guide
Create successful ePaper yourself
Turn your PDF publications into a flip-book with our unique Google optimized e-Paper software.
D e v e l o p e r ’ s G u i d e<br />
October 14, 2005 © 2005 Smarthome Technology
Developer’s <strong>Guide</strong> Page i<br />
Contents at a Glance<br />
INTRODUCTION............................................................................................ 1<br />
<strong>INSTEON</strong> BASICS ......................................................................................... 3<br />
Getting Started Quickly ............................................................................. 4<br />
About This Developer’s <strong>Guide</strong>.................................................................... 5<br />
<strong>INSTEON</strong> Overview.................................................................................. 11<br />
<strong>INSTEON</strong> Application Development Overview.......................................... 23<br />
<strong>INSTEON</strong> REFERENCE ................................................................................. 30<br />
<strong>INSTEON</strong> Messages ................................................................................. 31<br />
<strong>INSTEON</strong> Signaling Details ...................................................................... 46<br />
<strong>INSTEON</strong> Network Usage......................................................................... 59<br />
<strong>INSTEON</strong> BIOS (IBIOS) ........................................................................... 90<br />
SALad Language Documentation ........................................................... 132<br />
Smarthome Device Manager Reference ................................................. 209<br />
<strong>INSTEON</strong> Hardware Development Documentation................................. 229<br />
CONCLUSION............................................................................................ 237<br />
NOTES ...................................................................................................... 238<br />
October 14, 2005 © 2005 Smarthome Technology
Developer’s <strong>Guide</strong> Page ii<br />
Full Table of Contents<br />
INTRODUCTION............................................................................................ 1<br />
<strong>INSTEON</strong> BASICS ......................................................................................... 3<br />
Getting Started Quickly ............................................................................. 4<br />
About This Developer’s <strong>Guide</strong>.................................................................... 5<br />
About the Documentation .......................................................................... 6<br />
Getting Help ............................................................................................ 7<br />
Legal Information ..................................................................................... 8<br />
Revision History ....................................................................................... 9<br />
<strong>INSTEON</strong> Overview.................................................................................. 11<br />
Why <strong>INSTEON</strong>? .......................................................................................12<br />
Hallmarks of <strong>INSTEON</strong>..............................................................................14<br />
<strong>INSTEON</strong> Specifications ............................................................................15<br />
<strong>INSTEON</strong> Fundamentals............................................................................17<br />
<strong>INSTEON</strong> Device Communication.............................................................18<br />
<strong>INSTEON</strong> Message Repeating..................................................................20<br />
<strong>INSTEON</strong> Peer-to-Peer Networking ..........................................................22<br />
<strong>INSTEON</strong> Application Development Overview.......................................... 23<br />
Interfacing to an <strong>INSTEON</strong> Network ...........................................................24<br />
The Smarthome PowerLinc Controller ......................................................24<br />
Manager Applications ...............................................................................25<br />
SALad Applications ..................................................................................26<br />
SALad Overview ...................................................................................26<br />
SALad Integrated Development Environment ............................................26<br />
<strong>INSTEON</strong> SALad and PowerLinc Controller Architecture...............................28<br />
<strong>INSTEON</strong> Developer’s Kits.........................................................................29<br />
Software Developer’s Kit........................................................................29<br />
Hardware Development Modules .............................................................29<br />
<strong>INSTEON</strong> REFERENCE ................................................................................. 30<br />
<strong>INSTEON</strong> Messages ................................................................................. 31<br />
<strong>INSTEON</strong> Message Structure .....................................................................32<br />
Message Lengths ..................................................................................32<br />
Standard Message..............................................................................32<br />
Extended Message .............................................................................33<br />
Message Fields .....................................................................................34<br />
Device Addresses ...............................................................................34<br />
Message Flags ...................................................................................34<br />
Message Type Flags .........................................................................35<br />
Extended Message Flag ....................................................................36<br />
Message Retransmission Flags...........................................................36<br />
Command 1 and 2..............................................................................37<br />
User Data .........................................................................................37<br />
Message Integrity Byte .......................................................................37<br />
<strong>INSTEON</strong> Message Summary Table ............................................................38<br />
<strong>INSTEON</strong> Message Repetition ....................................................................40<br />
<strong>INSTEON</strong> Message Hopping ....................................................................40<br />
Message Hopping Control ....................................................................40<br />
October 14, 2005 © 2005 Smarthome Technology
Developer’s <strong>Guide</strong> Page iii<br />
Timeslot Synchronization ....................................................................40<br />
<strong>INSTEON</strong> Message Retrying....................................................................45<br />
<strong>INSTEON</strong> Signaling Details ...................................................................... 46<br />
<strong>INSTEON</strong> Packet Structure ........................................................................47<br />
Powerline Packets .................................................................................47<br />
RF Packets...........................................................................................48<br />
<strong>INSTEON</strong> Signaling ..................................................................................49<br />
Powerline Signaling ...............................................................................49<br />
BPSK Modulation................................................................................50<br />
Packet Timing....................................................................................51<br />
X10 Compatibility...............................................................................51<br />
Message Timeslots .............................................................................52<br />
Standard Message Timeslots .............................................................53<br />
Extended Message Timeslots.............................................................53<br />
<strong>INSTEON</strong> Powerline Data Rates ............................................................54<br />
RF Signaling.........................................................................................55<br />
Simulcasting ...........................................................................................57<br />
Powerline Simulcasting ..........................................................................57<br />
RF Simulcasting....................................................................................58<br />
RF/Powerline Synchronization .................................................................58<br />
<strong>INSTEON</strong> Network Usage......................................................................... 59<br />
<strong>INSTEON</strong> Commands ...............................................................................60<br />
<strong>INSTEON</strong> Command 1 and 2...................................................................61<br />
<strong>INSTEON</strong> Command Tables ....................................................................62<br />
<strong>INSTEON</strong> Common Commands.............................................................63<br />
NAK Reason Codes ..........................................................................68<br />
<strong>INSTEON</strong> Broadcast Commands ...........................................................69<br />
<strong>INSTEON</strong> Command Examples ................................................................71<br />
<strong>INSTEON</strong> Device Classes...........................................................................75<br />
Device Identification Broadcast ...............................................................75<br />
Device Type ......................................................................................75<br />
Device Attributes ...............................................................................75<br />
Firmware Revision..............................................................................76<br />
<strong>INSTEON</strong> Device Type Summary Table.....................................................76<br />
<strong>INSTEON</strong> Device Linking ...........................................................................77<br />
<strong>INSTEON</strong> Groups ..................................................................................77<br />
Groups and Links ...............................................................................77<br />
Examples of Groups............................................................................77<br />
Methods for Linking <strong>INSTEON</strong> Devices......................................................79<br />
Manual Linking ..................................................................................79<br />
Electronic Linking ...............................................................................79<br />
Example of an <strong>INSTEON</strong> Linking Session................................................80<br />
Example of <strong>INSTEON</strong> Group Conversation.................................................81<br />
<strong>INSTEON</strong> Link Database.........................................................................83<br />
PLC Link Database..............................................................................84<br />
Non-PLC Link Database.......................................................................86<br />
<strong>INSTEON</strong> Extended Messages ....................................................................87<br />
<strong>INSTEON</strong> Security....................................................................................88<br />
Linking Control .....................................................................................88<br />
Physical Possession of Devices .............................................................88<br />
Masking Non-linked Network Traffic ......................................................88<br />
Encryption within Extended Messages ......................................................89<br />
October 14, 2005 © 2005 Smarthome Technology
Developer’s <strong>Guide</strong> Page iv<br />
<strong>INSTEON</strong> BIOS (IBIOS) ........................................................................... 90<br />
IBIOS Flat Memory Model .........................................................................91<br />
Flat Memory Addressing.........................................................................92<br />
Flat Memory Map ..................................................................................94<br />
IBIOS Events ........................................................................................101<br />
IBIOS Serial Communication Protocol and Settings .....................................107<br />
IBIOS Serial Communication Protocol ....................................................108<br />
IBIOS RS232 Port Settings...................................................................108<br />
IBIOS USB Serial Interface...................................................................109<br />
IBIOS Serial Commands .........................................................................110<br />
IBIOS Serial Command Table ...............................................................111<br />
IBIOS Serial Command Examples..........................................................116<br />
Get Version .....................................................................................117<br />
Read and Write Memory....................................................................118<br />
Get Checksum on Region of Memory...................................................119<br />
Send <strong>INSTEON</strong> ................................................................................120<br />
Receive <strong>INSTEON</strong>.............................................................................121<br />
Send X10........................................................................................122<br />
Simulated Event ..............................................................................124<br />
IBIOS <strong>INSTEON</strong> Engine ..........................................................................126<br />
IBIOS Software Realtime Clock/Calendar ..................................................127<br />
IBIOS X10 Signaling ..............................................................................128<br />
IBIOS Input/Output ...............................................................................129<br />
IBIOS LED Flasher ..............................................................................129<br />
IBIOS SET Button Handler....................................................................129<br />
IBIOS Remote Debugging .......................................................................130<br />
IBIOS Watchdog Timer...........................................................................131<br />
SALad Language Documentation ........................................................... 132<br />
SALad Programming <strong>Guide</strong>......................................................................133<br />
Structure of a SALad Program...............................................................134<br />
The SALad Version of Hello World..........................................................136<br />
SALad Event Handling .........................................................................137<br />
Hello World 2 – Event Driven Version.....................................................139<br />
SALad coreApp Program ......................................................................141<br />
SALad Timers.....................................................................................142<br />
SALad Remote Debugging ....................................................................143<br />
Overwriting a SALad Application............................................................143<br />
Preventing a SALad Application from Running .........................................143<br />
SALad Language Reference .....................................................................144<br />
SALad Memory Addresses ....................................................................145<br />
SALad Instruction Set..........................................................................146<br />
SALad Universal Addressing Module (UAM) ..........................................147<br />
SALad Parameter Encoding................................................................148<br />
Parameter Reference Tables............................................................149<br />
SALad Instruction Summary Table ......................................................150<br />
SALad Integrated Development Environment User’s <strong>Guide</strong>...........................156<br />
SALad IDE Quickstart ..........................................................................157<br />
IDE Main Window................................................................................160<br />
IDE Menus ......................................................................................161<br />
Menu – File...................................................................................162<br />
Menu – Edit ..................................................................................164<br />
Menu – View.................................................................................166<br />
October 14, 2005 © 2005 Smarthome Technology
Developer’s <strong>Guide</strong> Page v<br />
Menu – Project..............................................................................167<br />
Menu – Mode ................................................................................167<br />
Menu – Virtual Devices...................................................................169<br />
Menu – Help .................................................................................170<br />
IDE Toolbar.....................................................................................171<br />
IDE Editor..........................................................................................173<br />
IDE Watch Panel.................................................................................176<br />
IDE Options Dialog Box........................................................................177<br />
Options – General ............................................................................178<br />
Options – Quick Tools .......................................................................178<br />
Options – Debugging ........................................................................180<br />
Options – Compiling .........................................................................181<br />
Options – Communications ................................................................182<br />
Options – Unit Defaults .....................................................................183<br />
Options – Directories ........................................................................183<br />
Options – Editor...............................................................................184<br />
Options – Saving..............................................................................185<br />
Options – Loading ............................................................................186<br />
Options – Project .............................................................................186<br />
IDE Windows and Inspectors ................................................................187<br />
Compile Errors.................................................................................188<br />
Comm Window ................................................................................189<br />
Comm Window – Raw Data.............................................................190<br />
Comm Window – PLC Events...........................................................190<br />
Comm Window – <strong>INSTEON</strong> Messages ...............................................192<br />
Comm Window – X10 Messages.......................................................193<br />
Comm Window – Conversation ........................................................194<br />
Comm Window – ASCII Window ......................................................195<br />
Comm Window – Debug Window .....................................................196<br />
Comm Window – Date/Time............................................................197<br />
Trace .............................................................................................198<br />
PLC Database ..................................................................................199<br />
SIM Control.....................................................................................200<br />
PLC Simulator Control Panel............................................................201<br />
PLC Simulator Memory Dump..........................................................202<br />
PLC Simulator Trace ......................................................................203<br />
IDE Virtual Devices .............................................................................204<br />
PLC Simulator..................................................................................205<br />
Virtual Powerline ..............................................................................206<br />
Virtual LampLinc ..............................................................................207<br />
IDE Keyboard Shortcuts.......................................................................208<br />
Smarthome Device Manager Reference ................................................. 209<br />
SDM Introduction ..................................................................................210<br />
SDM Quick Test.....................................................................................211<br />
SDM Test Using a Browser ...................................................................211<br />
SDM Test Using SDM’s Main Window......................................................212<br />
SDM Commands....................................................................................213<br />
SDM Commands – Getting Started ........................................................214<br />
SDM Commands – Home Control...........................................................215<br />
SDM Commands – Notification Responses ..............................................216<br />
SDM Commands – Direct Communications..............................................217<br />
SDM Commands – Memory ..................................................................218<br />
October 14, 2005 © 2005 Smarthome Technology
Developer’s <strong>Guide</strong> Page vi<br />
SDM Commands – PLC Control .............................................................219<br />
SDM Commands – Device Manager Control.............................................221<br />
SDM Commands – Link Database Management .......................................223<br />
SDM Commands – Timers ....................................................................225<br />
SDM Windows Registry Settings...............................................................228<br />
<strong>INSTEON</strong> Hardware Development Documentation................................. 229<br />
Hardware Overview ...............................................................................229<br />
Functional Block Diagram.....................................................................230<br />
HDK Physical Diagrams........................................................................231<br />
Hardware Reference Designs...................................................................233<br />
HDK Isolated Main Board .....................................................................234<br />
HDK Non-Isolated Main Board...............................................................235<br />
HDK Daughter Board ...........................................................................236<br />
CONCLUSION............................................................................................ 237<br />
NOTES ...................................................................................................... 238<br />
October 14, 2005 © 2005 Smarthome Technology
Date Author Change<br />
Developer’s <strong>Guide</strong> Page vii<br />
Publication Dates<br />
06-21-05 Bill Morgan Initial release.<br />
10-14-05 Paul Darbee Release for comment. Major editing and additions.<br />
October 14, 2005 © 2005 Smarthome Technology
INTRODUCTION<br />
Developer’s <strong>Guide</strong> Page 1<br />
A TV automatically turns on the surround sound amplifier, a smart microwave oven<br />
downloads new cooking recipes, a thermostat automatically changes to its energy<br />
saving setpoint when the security system is enabled, bathroom floors and towel<br />
racks heat up when the bath runs, an email alert goes out when there is water in the<br />
basement. When did the Jetson-style home of the future become a reality? When<br />
<strong>INSTEON</strong>—the new technology standard for advanced home control—arrived.<br />
<strong>INSTEON</strong> enables product developers to create these distinctive solutions for<br />
homeowners, and others yet unimagined, by delivering on the promise of a truly<br />
connected ‘smart home.’<br />
<strong>INSTEON</strong> is a cost-effective dual band network technology optimized for home<br />
management and control. <strong>INSTEON</strong>-networked Electronic Home Improvement<br />
products can interact with one another, and with people, in new ways that will<br />
improve the comfort, safety, convenience and value of homes around the world.<br />
For a brief introduction to <strong>INSTEON</strong> see <strong>INSTEON</strong> Overview.<br />
This Developer’s <strong>Guide</strong> is part of the <strong>INSTEON</strong> Software and Hardware Development<br />
Kits that Smarthome provides to Independent Software Vendors (ISVs) and Original<br />
Equipment Manufacturers (OEMs) who wish to create software and hardware<br />
systems that work with <strong>INSTEON</strong>.<br />
October 14, 2005 © 2005 Smarthome Technology
In This <strong>INSTEON</strong> Developer’s <strong>Guide</strong><br />
Developer’s <strong>Guide</strong> Page 2<br />
<strong>INSTEON</strong> BASICS<br />
Gives an overview of <strong>INSTEON</strong>, including the following sections:<br />
• Getting Started Quickly<br />
Points out the highlights of this Developer’s <strong>Guide</strong> for those who wish to start<br />
coding as quickly as possible.<br />
• About This Developer’s <strong>Guide</strong><br />
Discusses document filtering options and document conventions, where to get<br />
support, and legal information.<br />
• <strong>INSTEON</strong> Overview<br />
Familiarizes you with the background, design goals, and capabilities of<br />
<strong>INSTEON</strong>.<br />
• <strong>INSTEON</strong> Application Development Overview<br />
Explains how developers can create applications that orchestrate the behavior<br />
of <strong>INSTEON</strong>-networked devices.<br />
<strong>INSTEON</strong> REFERENCE<br />
Provides complete reference documentation for <strong>INSTEON</strong>, including the following<br />
sections:<br />
• <strong>INSTEON</strong> Messages<br />
Gives the structure and contents of <strong>INSTEON</strong> messages and discusses<br />
message retransmission.<br />
• <strong>INSTEON</strong> Signaling Details<br />
Explains how <strong>INSTEON</strong> messages are broken up into packets and transmitted<br />
over both the powerline and radio using synchronous simulcasting.<br />
• <strong>INSTEON</strong> Network Usage<br />
Covers <strong>INSTEON</strong> Commands and Device Classes, explains how devices are<br />
logically linked together, and discusses <strong>INSTEON</strong> network security.<br />
• <strong>INSTEON</strong> BIOS (IBIOS)<br />
Describes the <strong>INSTEON</strong> Basic Input/Output System as it is implemented in<br />
the Smarthome PowerLinc V2 Controller (PLC).<br />
• SALad Language Documentation<br />
Documents the SALad application programming language. SALad enables you<br />
to write custom device personalities, install them on <strong>INSTEON</strong> devices, and<br />
debug them remotely.<br />
• Smarthome Device Manager Reference<br />
Describes the Smarthome Device Manager program.<br />
• <strong>INSTEON</strong> Hardware Development Documentation<br />
Describes the <strong>INSTEON</strong> Hardware Development Kit for powerline applications.<br />
CONCLUSION<br />
Recaps the main features of <strong>INSTEON</strong>.<br />
October 14, 2005 © 2005 Smarthome Technology
<strong>INSTEON</strong> BASICS<br />
In This Section<br />
Developer’s <strong>Guide</strong> Page 3<br />
Getting Started Quickly<br />
Points out the highlights of this Developer’s <strong>Guide</strong> for those who wish to start<br />
coding as quickly as possible.<br />
About This Developer’s <strong>Guide</strong><br />
Discusses document conventions, where to get support, and legal information.<br />
<strong>INSTEON</strong> Overview<br />
Familiarizes you with the background, design goals, and capabilities of <strong>INSTEON</strong>.<br />
<strong>INSTEON</strong> Application Development Overview<br />
Explains how developers can create applications that orchestrate the behavior of<br />
<strong>INSTEON</strong>-networked devices.<br />
October 14, 2005 © 2005 Smarthome Technology
Getting Started Quickly<br />
Developer’s <strong>Guide</strong> Page 4<br />
<strong>INSTEON</strong> devices communicate by sending <strong>INSTEON</strong> messages. The Smarthome<br />
PowerLinc Controller (PLC) is an <strong>INSTEON</strong> device that also has a serial port that you<br />
connect to your PC. You can write applications that run on the PLC using tools<br />
documented in the SALad Integrated Development Environment User’s <strong>Guide</strong>.<br />
What to Look at First<br />
For an accelerated introduction to using the PLC and SALad to control and program<br />
<strong>INSTEON</strong> devices, follow these steps in sequence:<br />
1. Review the <strong>INSTEON</strong> SALad and PowerLinc Controller Architecture and <strong>INSTEON</strong><br />
Device Communication diagrams to see how things fit together.<br />
2. Review the IBIOS Serial Communication Protocol and Settings section to see how<br />
the serial protocol works.<br />
3. Review the IBIOS Serial Command Examples section to see how to use IBIOS<br />
Serial Commands directly.<br />
4. Review the SALad IDE Quickstart section.<br />
5. Review the <strong>INSTEON</strong> Messages section for more detailed information on the<br />
<strong>INSTEON</strong> protocol.<br />
6. Review the <strong>INSTEON</strong> Network Usage section for details about <strong>INSTEON</strong><br />
commands, device classes, device linking using Groups, and security issues.<br />
Summary Tables<br />
Sections of this Developer’s <strong>Guide</strong> that you will reference often are:<br />
1. The <strong>INSTEON</strong> Message Summary Table, which enumerates all possible <strong>INSTEON</strong><br />
message types.<br />
2. The <strong>INSTEON</strong> Common Command Summary Table and <strong>INSTEON</strong> Broadcast<br />
Command Summary Table, which enumerate all of the <strong>INSTEON</strong> Commands that<br />
can appear in <strong>INSTEON</strong> messages.<br />
3. The IBIOS Event Summary Table, which enumerates all of the events that IBIOS<br />
can generate.<br />
4. The IBIOS Serial Command Summary Table, which enumerates all of the<br />
commands for interacting serially with the PLC.<br />
5. The Flat Memory Map, which shows where everything is in the PLC’s memory.<br />
6. The SALad Instruction Summary Table, which lists the SALad instruction set.<br />
October 14, 2005 © 2005 Smarthome Technology
About This Developer’s <strong>Guide</strong><br />
In This Section<br />
About the Documentation<br />
Lists document features and conventions.<br />
Getting Help<br />
Provides sources of additional support for developers.<br />
Developer’s <strong>Guide</strong> Page 5<br />
Legal Information<br />
Gives the Terms of Use plus trademark, patent, and copyright information.<br />
Revision History<br />
Shows a list of changes to this document.<br />
October 14, 2005 © 2005 Smarthome Technology
About the Documentation<br />
Document Conventions<br />
Developer’s <strong>Guide</strong> Page 6<br />
The following table shows the typographic conventions used in this <strong>INSTEON</strong><br />
Developer’s <strong>Guide</strong>.<br />
Convention Description Example<br />
Monospace Indicates source code, code<br />
examples, code lines embedded in<br />
text, and variables and code<br />
elements<br />
DST EQU 0x0580<br />
Angle Brackets < and > Indicates user-supplied parameters <br />
Vertical Bar | Indicates a choice of one of several<br />
alternatives<br />
Ellipsis … Used to imply additional text “Text …”<br />
<br />
0xNN Hexadecimal number 0xFF, 0x29, 0x89AB<br />
⇒ Range of values, including the<br />
beginning and ending values<br />
0x00 ⇒ 0x0D<br />
October 14, 2005 © 2005 Smarthome Technology
Getting Help<br />
<strong>INSTEON</strong> Support<br />
Developer’s <strong>Guide</strong> Page 7<br />
Smarthome is keenly interested in supporting the community of <strong>INSTEON</strong><br />
developers. If you are having trouble finding the answers you need in this <strong>INSTEON</strong><br />
Developer’s <strong>Guide</strong>, you can get more help by accessing the <strong>INSTEON</strong> Developer’s<br />
Forum or by emailing sdk@insteon.net.<br />
<strong>INSTEON</strong> Developer’s Forum<br />
When you purchased the <strong>INSTEON</strong> Software Developer’s Kit, you received a<br />
username and password for accessing the Developer’s Forum at<br />
http://insteon.net/sdk/forum. The Forum contains a wealth of information for<br />
developers, including<br />
• Frequently asked questions<br />
• Software downloads, including the SALad IDE (Integrated Development<br />
Environment), and Smarthome Device Manager<br />
• Documentation updates<br />
• Sample code<br />
• Discussion forums<br />
Providing Feedback<br />
To provide feedback about this documentation, go to the <strong>INSTEON</strong> Developer’s<br />
Forum or send email to sdk@insteon.net.<br />
October 14, 2005 © 2005 Smarthome Technology
Legal Information<br />
Terms of Use<br />
Developer’s <strong>Guide</strong> Page 8<br />
This <strong>INSTEON</strong> Developer’s <strong>Guide</strong> is supplied to you by Smarthome, Inc.<br />
(Smarthome) in consideration of your agreement to the following terms. Your use or<br />
installation of this <strong>INSTEON</strong> Developer’s <strong>Guide</strong> constitutes acceptance of these<br />
terms. If you do not agree with these terms, please do not use or install this<br />
<strong>INSTEON</strong> Developer’s <strong>Guide</strong>.<br />
In consideration of your agreement to abide by the following terms, and subject to<br />
these terms, Smarthome grants you a personal, non-exclusive license, under<br />
Smarthome's intellectual property rights in this <strong>INSTEON</strong> Developer’s <strong>Guide</strong>, to use<br />
this <strong>INSTEON</strong> Developer’s <strong>Guide</strong>; provided that no license is granted herein under<br />
any patents that may be infringed by your works, modifications of works, derivative<br />
works or by other works in which the information in this <strong>INSTEON</strong> Developer’s <strong>Guide</strong><br />
may be incorporated. No names, trademarks, service marks or logos of Smarthome,<br />
Inc. or <strong>INSTEON</strong> may be used to endorse or promote products derived from the<br />
<strong>INSTEON</strong> Developer’s <strong>Guide</strong> without specific prior written permission from<br />
Smarthome, Inc. Except as expressly stated herein, no other rights or licenses,<br />
express or implied, are granted by Smarthome and nothing herein grants any license<br />
under any patents except claims of Smarthome patents that cover this <strong>INSTEON</strong><br />
Developer’s <strong>Guide</strong> as originally provided by Smarthome, and only to the extent<br />
necessary to use this <strong>INSTEON</strong> Developer’s <strong>Guide</strong> as originally provided by<br />
Smarthome. Smarthome provides this <strong>INSTEON</strong> Developer’s <strong>Guide</strong> on an "AS IS"<br />
basis.<br />
SMARTHOME MAKES NO WARRANTIES, EXPRESS OR IMPLIED, INCLUDING WITHOUT<br />
LIMITATION THE IMPLIED WARRANTIES OF NON-INFRINGEMENT,<br />
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE, REGARDING THIS<br />
<strong>INSTEON</strong> DEVELOPER’S GUIDE OR ITS USE, ALONE OR IN COMBINATION WITH ANY<br />
PRODUCT.<br />
IN NO EVENT SHALL SMARTHOME BE LIABLE FOR ANY SPECIAL, INDIRECT,<br />
INCIDENTAL OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,<br />
PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR<br />
PROFITS; OR BUSINESS INTERRUPTION) ARISING IN ANY WAY OUT OF THE USE,<br />
REPRODUCTION, MODIFICATION AND/OR DISTRIBUTION OF THIS <strong>INSTEON</strong><br />
DEVELOPER’S GUIDE, HOWEVER CAUSED AND WHETHER UNDER THEORY OF<br />
CONTRACT, TORT (INCLUDING NEGLIGENCE), STRICT LIABILITY OR OTHERWISE,<br />
EVEN IF SMARTHOME HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.<br />
Trademarks and Patents<br />
Smarthome, <strong>INSTEON</strong>, PowerLinc, ControLinc, LampLinc, SwitchLinc, RemoteLinc,<br />
Electronic Home Improvement, Smarthome Device Manager, Home Network<br />
Language, and Plug-n-Tap are trademarks of Smarthome, Inc.<br />
<strong>INSTEON</strong> networking technology is covered by pending U.S. and foreign patents.<br />
Copyright<br />
© Copyright 2005 Smarthome, Inc. 16542 Millikan Ave., Irvine, CA 92606-5027;<br />
800-SMARTHOME (800-762-7846), 949-221-9200, www.smarthome.com. All rights<br />
reserved.<br />
October 14, 2005 © 2005 Smarthome Technology
Revision History<br />
Release<br />
Date<br />
Author Description<br />
10/5/04 BM Initial Draft.<br />
10/19/04 BM Alpha release of SDK.<br />
10/19/04 BM Added Flags to the Memory Map.<br />
Developer’s <strong>Guide</strong> Page 9<br />
10/22/04 BM Removed SALad NTL documentation and put in external document. Editing<br />
changes.<br />
10/27/04 BM Editorial changes. Fixed version in header to match version on title page.<br />
11/02/04 BM Updated serial command section. Created index and started adding entries.<br />
Updated section 6 (<strong>INSTEON</strong> Messages). Added Device Types. Removed<br />
Examples section, and put example code in external directory.<br />
11/05/04 BM Editorial Changes.<br />
11/15/04 BM Editorial Changes.<br />
11/22/04 BM Editorial Changes. Reformatted document. Removed Warning and Reserved<br />
areas from Flat Memory M. Added new memory map for flat / absolute<br />
address space. Added serial commands with examples relative to previous<br />
serial commands.<br />
11/29/04 BM Added changes from technical review. Removed CRC from <strong>INSTEON</strong> message<br />
descriptions. Added SALad Assembler documentation. Added USB notes.<br />
1/3/05 BM Added changes to Peek direct command description to include address autoincrement<br />
feature. Updated device types. Reformatted document. Added<br />
SALad detailed instructions. Updated Link Data Table. Added table for NAK<br />
reasons. Added <strong>INSTEON</strong> enrollment description. Initial release to select beta<br />
reviewers.<br />
1/14/05 BM Removed CRC columns and rows of message tables and rephrased CRC<br />
description near message tables. Added Bit 0 for the Total Hops and rephrased<br />
hops descriptions.<br />
1/21/05 BM Added IBIOS Serial Command Examples.<br />
1/31/05 BM Added more PowerLinc Serial examples. Updated SALad Event Handling.<br />
Updated hypertext bookmark links. Editing changes.<br />
2/3/05 BM Updated Flat Memory M.<br />
2/10/05 BM Updated serial command checksum description. Updated Control and<br />
RS_Control registers in Flat Memory M.<br />
3/14/05 BM Redesign of Device Types and Network Management. Document formatting<br />
changes. Updated Flat Memory M. Updated SALad SALad Instruction<br />
Summary Table and SALad Parameter Encoding. Updated <strong>INSTEON</strong> Command<br />
Tables.<br />
3/15/05 BM Updated <strong>INSTEON</strong> Command Tables. Added latest IDE documentation.<br />
3/18/05 BM Updated SALad Instruction Summary. Removed AJUMP, ACALL, PAUSE,<br />
APROC. Updated command codes for SEND$, SENDEXT$, RANDOMIZE.<br />
Renamed RJUMP to JUMP, RCALL to CALL, RPROC to PROC. Added new<br />
command ENROLLMENT. Editorial Changes<br />
October 14, 2005 © 2005 Smarthome Technology
Developer’s <strong>Guide</strong> Page 10<br />
3/21/05 BM Editorial changes. Updated Flat Memory M. Updated IBIOS Serial Command<br />
Examples.<br />
3/23/05 BM Removed blank topic headings.<br />
3/28/05 BM Updated Flat Memory M for PowerLinc Controller version 2.6. Added<br />
EventMask 0x016F register, and updated I_Control register 0x0142.<br />
4/11/05 BM Updated SALad Instruction Summary. Updated Flat Memory M.<br />
4/13/05 BM Added Receive <strong>INSTEON</strong> example. Updated serial communications sections to<br />
remove 0x0d transmission.<br />
4/21/05 BM Updated data returned by Get Version serial command (0x48). Updated Event<br />
Report serial command (0x45).<br />
5/16/05 BM Updated SALad TEST instruction to “jump if false”. Updated SALad FIND<br />
instruction description.<br />
6/3/05 BM Updated SALad Flat Memory M. Added Debug Report to <strong>INSTEON</strong> Broadcast<br />
Commands section. Updated Event Table.<br />
6/15/05 BM Added <strong>INSTEON</strong> Hardware Development Documentation.<br />
6/20/05 BV Updated product names referenced in document. Fixed error in description of<br />
SALad FIND instruction for finding Master or Slave device. Fixed error in Peek<br />
and Poke Notes (there is only one Set Hi command 0x27).<br />
6/21/05 BV Updated the FIND instruction (find empty returns a pointer to DB_H, not<br />
DB_0).<br />
7/21/05 BV Updated Device Type 0x0007 to ‘Reserved for future use’. Used ⇒, instead of<br />
‘-‘ to mean an address range to avoid confusion with the minus symbol.<br />
Updated command 0x48. Updated references to Controller and Responder.<br />
Updated DB_0 ⇒ DB_8 to clarify message construction.<br />
8/16/05 PVD Began major rewrite, including additional material and reformatting.<br />
10/7/05 PVD Pre-release for comment. Major editing and additions, but incomplete. Areas<br />
needing attention marked.<br />
10/14/05 PVD Release for comment. Major editing and additions.<br />
October 14, 2005 © 2005 Smarthome Technology
<strong>INSTEON</strong> Overview<br />
Developer’s <strong>Guide</strong> Page 11<br />
<strong>INSTEON</strong> enables simple, low-cost devices to be networked together using the<br />
powerline, radio frequency (RF), or both. All <strong>INSTEON</strong> devices are peers, meaning<br />
that any device can transmit, receive, or repeat 1 other messages, without requiring a<br />
master controller or complex routing software. Adding more devices makes an<br />
<strong>INSTEON</strong> network more robust, by virtue of a simple protocol for communication<br />
retransmissions and retries. On the powerline, <strong>INSTEON</strong> devices are compatible 2<br />
with legacy X10 devices.<br />
This section explains why <strong>INSTEON</strong> has these properties and explains them further<br />
without going into the details.<br />
In this section<br />
Why <strong>INSTEON</strong>?<br />
Explains why Smarthome undertook the development of <strong>INSTEON</strong>.<br />
Hallmarks of <strong>INSTEON</strong><br />
Gives the ‘project pillars’ and main properties of <strong>INSTEON</strong>.<br />
<strong>INSTEON</strong> Specifications<br />
Shows the main features of <strong>INSTEON</strong> in table form.<br />
<strong>INSTEON</strong> Fundamentals<br />
Shows how <strong>INSTEON</strong> devices communicate using both powerline and radio, how<br />
all <strong>INSTEON</strong> devices repeat 1 <strong>INSTEON</strong> messages, and how all <strong>INSTEON</strong> devices<br />
are peers.<br />
<strong>INSTEON</strong> Application Development Overview<br />
Explains how developers can create applications that orchestrate the behavior of<br />
<strong>INSTEON</strong>-networked devices.<br />
October 14, 2005 © 2005 Smarthome Technology
Why <strong>INSTEON</strong>?<br />
Developer’s <strong>Guide</strong> Page 12<br />
<strong>INSTEON</strong> is the creation of Smarthome, the world’s leading authority on electronic<br />
home improvement. Smarthome is organized into three divisions—Smarthome.com,<br />
“the Amazon of electronic home improvement,” Smarthome Design, creators of bestin-class<br />
home control products, and Smarthome Technology, the pioneering<br />
architects of <strong>INSTEON</strong>. With Smarthome.com’s global distribution channel,<br />
Smarthome Design’s product development and manufacturing resources, and<br />
Smarthome Technology’s ongoing innovation, Smarthome is uniquely positioned to<br />
support and encourage <strong>INSTEON</strong> product developers.<br />
But why did Smarthome undertake the complex task of creating an entirely new<br />
home-control networking technology in the first place?<br />
Smarthome has been a leading supplier of devices and equipment to home<br />
automation installers and enthusiasts since 1992. Now selling over 5,000 products<br />
into more than 130 countries, Smarthome has first-hand experience dealing directly<br />
with people all over the world who have installed lighting control, whole-house<br />
automation, security and surveillance systems, pet care devices, gadgets, and home<br />
entertainment equipment. Over the years, by talking to thousands of customers<br />
through its person-to-person customer support operation, Smarthome has become<br />
increasingly concerned about the mismatch between the dream of living in a<br />
responsive, aware, automated home and the reality of existing home-control<br />
technologies.<br />
Today’s homes are stuffed with high-tech appliances, entertainment gear,<br />
computers, and communications gadgets. Utilities, such as electricity, lighting,<br />
plumbing, heating and air conditioning are so much a part of modern life that they<br />
almost go unnoticed. But these systems and devices all act independently of each<br />
other—there still is nothing that can link them all together. Houses don’t know that<br />
people live in them. Lights happily burn when no one needs them, HVAC is<br />
insensitive to the location and comfort of people, pipes can burst without anyone<br />
being notified, and sprinklers dutifully water the lawn even while it’s raining.<br />
For a collection of independent objects to behave with a unified purpose, the objects<br />
must be able to communicate with each other. When they do, new, sometimesunpredictable<br />
properties often emerge. In biology, animals emerged when nervous<br />
systems evolved. The Internet emerged when telecommunications linked computers<br />
together. The global economy emerges from transactions involving a staggering<br />
amount of communication. But there is no such communicating infrastructure in our<br />
homes out of which we might expect new levels of comfort, safety and convenience<br />
to emerge. There is nothing we use routinely in our homes that links our light<br />
switches or our door locks, for instance, to our PCs or our remote controls.<br />
It’s not that such systems don’t exist at all. Just as there were automobiles for<br />
decades before Henry Ford made cars available to everyone, there are now and have<br />
been for some time systems that can perform home automation tasks. On the high<br />
end, all kinds of customized systems are available for the affluent, just as the rich<br />
could buy a Stanley Steamer or a Hupmobile in the late 1800s. At the low end, X10<br />
powerline signaling technology has been around since the 1970s, but its early<br />
adoption is its limiting factor—it is too unreliable and inflexible to be useful as an<br />
infrastructure network.<br />
Smarthome is a major distributor of devices that use X10 signaling. In 1997, aware<br />
of the reliability problems its customers were having with X10 devices available at<br />
October 14, 2005 © 2005 Smarthome Technology
Developer’s <strong>Guide</strong> Page 13<br />
the time, Smarthome developed and began manufacturing its own ‘Linc’ series of<br />
improved X10 devices, including controllers, dimmers, switches, computer interfaces<br />
and signal boosters. Despite the enhanced performance enjoyed by Linc products, it<br />
was still mostly do-it-yourselfers and hobbyists who were buying and installing them.<br />
Smarthome knew that a far more robust and flexible networking standard would<br />
have to replace X10 before a truly intelligent home could emerge. Smarthome<br />
wanted a technology that would meet the simplicity, reliability, and cost expectations<br />
of the masses—mainstream consumers who want immediate benefits, not toys.<br />
In 2001, Smarthome’s engineers were well aware of efforts by others to bring about<br />
the home of the future. The aging X10 protocol was simply too limiting with its tiny<br />
command set and unacknowledged, ‘press and pray’ signaling over the powerline.<br />
CEBus had tried to be everything to everybody, suffering from high cost due to<br />
overdesign by a committee of engineers. Although CEBus did become an official<br />
standard (EIA-600), developers did not incorporate it into real-world products.<br />
Radio-only communication protocols, such as Z-Wave and ZigBee, not only required<br />
complex routing strategies and a confusing array of different types of network<br />
masters, slaves, and other modules, but radio alone might not be reliable enough<br />
when installed in metal switch junction boxes or other RF-blocking locations.<br />
BlueTooth radio has too short a range, WiFi radio is too expensive, and high-speed<br />
powerline protocols are far too complex to be built into commodity products such as<br />
light switches, door locks, or thermostats. Overall, it seemed that everything<br />
proposed or available was too overdesigned and therefore would cost too much to<br />
become a commodity for the masses in the global economy.<br />
So, in 2001, Smarthome decided to take its destiny into its own hands and set out to<br />
specify an ideal home control network, one that would be simple, robust and<br />
inexpensive enough to link everything to everything else. <strong>INSTEON</strong> was born.<br />
October 14, 2005 © 2005 Smarthome Technology
Hallmarks of <strong>INSTEON</strong><br />
Developer’s <strong>Guide</strong> Page 14<br />
These are the project pillars that Smarthome decided upon to guide the development<br />
of <strong>INSTEON</strong>. Products networked with <strong>INSTEON</strong> had to be:<br />
Instantly Responsive<br />
<strong>INSTEON</strong> devices respond to commands with no perceptible delay. <strong>INSTEON</strong>’s<br />
signaling speed is optimized for home control—fast enough for quick response, while<br />
still allowing reliable networking using low-cost components.<br />
Easy to Install<br />
Installation in existing homes does not require any new wiring, because <strong>INSTEON</strong><br />
products communicate over powerline wires or they use the airwaves. Users never<br />
have to deal with network enrollment issues because all <strong>INSTEON</strong> devices have an ID<br />
number pre-loaded at the factory—<strong>INSTEON</strong> devices join the network as soon as<br />
they’re powered up.<br />
Simple to Use<br />
Getting one <strong>INSTEON</strong> device to control another is very simple—just press and hold a<br />
button on each device for 10 seconds, and they’re linked. Because commands are<br />
confirmed, <strong>INSTEON</strong> products can provide instant feedback to the user, making them<br />
straightforward to use and ‘guest friendly.’<br />
Reliable<br />
An <strong>INSTEON</strong> network becomes more robust and reliable as it is expanded because<br />
every <strong>INSTEON</strong> device repeats 1 messages received from other <strong>INSTEON</strong> devices.<br />
Dual band communications using both the powerline and the airwaves ensures that<br />
there are multiple pathways for messages to travel.<br />
Affordable<br />
<strong>INSTEON</strong> software is simple and compact, because all <strong>INSTEON</strong> devices send and<br />
receive messages in exactly the same way, without requiring a special network<br />
controller or complex routing algorithms. The cost of networking products with<br />
<strong>INSTEON</strong> is held to at an absolute minimum because <strong>INSTEON</strong> is designed<br />
specifically for home control applications, and not for transporting large amounts of<br />
data.<br />
Compatible with X10<br />
<strong>INSTEON</strong> and X10 signals can coexist with each other on the powerline without<br />
mutual interference. Designers are free to create hybrid <strong>INSTEON</strong>/X10 products that<br />
operate equally well in both environments, allowing current users of legacy X10<br />
products to easily upgrade to <strong>INSTEON</strong> without making their investment in X10<br />
obsolete.<br />
October 14, 2005 © 2005 Smarthome Technology
<strong>INSTEON</strong> Specifications<br />
Developer’s <strong>Guide</strong> Page 15<br />
The most important property of <strong>INSTEON</strong> is its no-frills simplicity.<br />
<strong>INSTEON</strong> messages are fixed in length and synchronized to the AC powerline zero<br />
crossings. They do not contain routing information beyond a source and destination<br />
address. <strong>INSTEON</strong> is reliable and affordable because it is optimized for command<br />
and control, not high-speed data transport. <strong>INSTEON</strong> allows infrastructure devices<br />
like light switches and sensors to be networked together in large numbers, at low<br />
cost. <strong>INSTEON</strong> stands on its own, but can also bridge to other networks, such as<br />
WiFi LANs, the Internet, telephony, and entertainment distribution systems. Such<br />
bridging allows <strong>INSTEON</strong> to be part of very sophisticated integrated home control<br />
environments.<br />
The following table shows the main features of <strong>INSTEON</strong> at a glance.<br />
<strong>INSTEON</strong> Property Specification<br />
Network Dual band (RF and powerline)<br />
Peer-to-Peer<br />
Mesh Topology<br />
Unsupervised<br />
No routing tables<br />
Protocol All devices are two-way Repeaters 1<br />
Messages acknowledged<br />
Retry if not acknowledged<br />
Synchronized to powerline<br />
X10 Compatibility 2 <strong>INSTEON</strong> devices can send and receive X10 commands<br />
<strong>INSTEON</strong> devices do not repeat or amplify X10<br />
Data Rate<br />
Message Types<br />
Message Format, Bytes<br />
Devices Supported<br />
<strong>INSTEON</strong> Engine<br />
Memory Requirements<br />
Instantaneous 13,165 bits/sec<br />
Sustained 2,880 bits/sec<br />
Standard 10 Bytes<br />
Extended 24 Bytes<br />
From Address 3<br />
To Address 3<br />
Flags 1<br />
Command 2<br />
User Data 14 (Extended Messages only)<br />
Message Integrity 1<br />
Unique IDs 16,777,216<br />
Device Types 65,536<br />
Commands 65,536<br />
Groups per Device 256<br />
Members within a Group Limited only by memory<br />
RAM 80 Bytes<br />
ROM 3K Bytes<br />
October 14, 2005 © 2005 Smarthome Technology
<strong>INSTEON</strong> Property Specification<br />
Typical <strong>INSTEON</strong> Application<br />
Memory Requirements<br />
(Light Switch, Lamp Dimmer)<br />
Device Installation Plug-in<br />
Wire-in<br />
Battery Operated<br />
Developer’s <strong>Guide</strong> Page 16<br />
RAM 256 Bytes<br />
EEPROM 256 Bytes<br />
Flash 7K Bytes<br />
Device Setup Plug-n-Tap manual linking<br />
PC or Controller<br />
Security Physical device possession<br />
Address masking<br />
Encrypted message payloads<br />
Application Development IDE (Integrated Development Environment)<br />
SALad interpreted language<br />
Software and Hardware Development Kits<br />
Powerline Physical Layer<br />
RF Physical Layer<br />
Frequency 131.65 KHz<br />
Modulation BPSK<br />
Min Transmit Level 3.16 Vpp into 5 Ohms<br />
Min Receive Level 10 mV<br />
Phase Bridging <strong>INSTEON</strong> RF or hardware<br />
Frequency 904 MHz<br />
Modulation FSK<br />
Sensitivity -103 dbm<br />
Range 150 ft unobstructed line-of-sight<br />
October 14, 2005 © 2005 Smarthome Technology
<strong>INSTEON</strong> Fundamentals<br />
In this section<br />
Developer’s <strong>Guide</strong> Page 17<br />
<strong>INSTEON</strong> Device Communication<br />
Shows how <strong>INSTEON</strong> devices communicate over the powerline and via RF.<br />
<strong>INSTEON</strong> Message Repeating<br />
Explains why network reliability improves when additional <strong>INSTEON</strong> devices are<br />
added.<br />
<strong>INSTEON</strong> Peer-to-Peer Networking<br />
Shows how any <strong>INSTEON</strong> device can act as a Controller (sending messages),<br />
Responder (receiving messages), or Repeater 1 (relaying messages).<br />
October 14, 2005 © 2005 Smarthome Technology
<strong>INSTEON</strong> Device Communication<br />
Developer’s <strong>Guide</strong> Page 18<br />
Devices communicate with each other using the <strong>INSTEON</strong> protocol over the air via<br />
radio frequency (RF) and over the powerline as illustrated below.<br />
PC<br />
Serial USB / RS232 / Ethernet<br />
<strong>INSTEON</strong><br />
PL / Serial<br />
Device<br />
Powerline <strong>INSTEON</strong> & X10<br />
Powerline <strong>INSTEON</strong> & X10<br />
Home's Electrical Wiring Phase 1<br />
<strong>INSTEON</strong><br />
PL<br />
Devices<br />
<strong>INSTEON</strong><br />
PL / RF<br />
Device<br />
Powerline <strong>INSTEON</strong><br />
Powerline X10<br />
X10 Devices<br />
<strong>INSTEON</strong><br />
RF<br />
Devices<br />
RF <strong>INSTEON</strong><br />
RF <strong>INSTEON</strong><br />
<strong>INSTEON</strong><br />
PL / RF<br />
Device<br />
Powerline <strong>INSTEON</strong><br />
Home's Electrical Wiring Phase 2<br />
Powerline <strong>INSTEON</strong> & X10<br />
<strong>INSTEON</strong><br />
PL<br />
Devices<br />
Powerline X10<br />
X10 Devices<br />
Electrical power is most commonly distributed to homes in North America as splitphase<br />
220-volt alternating current (220 VAC). At the main electrical junction box to<br />
the home, the single three-wire 220 VAC powerline is split into a pair of two-wire<br />
110 VAC powerlines, known as Phase 1 and Phase 2. Phase 1 wiring usually powers<br />
half the circuits in the home, and Phase 2 powers the other half.<br />
<strong>INSTEON</strong> devices communicate with each other over the powerline using the<br />
<strong>INSTEON</strong> Powerline protocol, which will be described in detail below (see <strong>INSTEON</strong><br />
Messages and <strong>INSTEON</strong> Signaling Details).<br />
October 14, 2005 © 2005 Smarthome Technology
Developer’s <strong>Guide</strong> Page 19<br />
Existing X10 devices also communicate over the powerline using the X10 protocol.<br />
The <strong>INSTEON</strong> Powerline protocol is compatible 2 with the X10 protocol, meaning that<br />
designers can create <strong>INSTEON</strong> devices that can also listen and talk to X10 devices.<br />
X10 devices, however, are insensitive to the <strong>INSTEON</strong> Powerline protocol.<br />
<strong>INSTEON</strong> devices containing RF hardware may optionally communicate with other<br />
<strong>INSTEON</strong> RF devices using the <strong>INSTEON</strong> RF protocol.<br />
<strong>INSTEON</strong> devices that can use both the <strong>INSTEON</strong> Powerline protocol and the<br />
<strong>INSTEON</strong> RF protocol solve a significant problem encountered by devices that can<br />
only communicate via the powerline. Powerline signals originating on the opposite<br />
powerline phase from a powerline receiver are severely attenuated, because there is<br />
no direct circuit connection for them to travel over.<br />
A traditional solution to this problem is to connect a signal coupling device between<br />
the powerline phases, either by hardwiring it in at a junction box or by plugging it<br />
into a 220 VAC outlet. <strong>INSTEON</strong> automatically solves the powerline phase coupling<br />
problem through the use of <strong>INSTEON</strong> devices capable of both powerline and RF<br />
messaging. <strong>INSTEON</strong> RF messaging bridges the powerline phases whenever at least<br />
one <strong>INSTEON</strong> PL/RF device is installed on each powerline phase.<br />
When suitably equipped with a dedicated serial interface, such as USB, RS232, or<br />
Ethernet, <strong>INSTEON</strong> devices can also interface with computers and other digital<br />
equipment. In the figure above, an <strong>INSTEON</strong> device is shown communicating with a<br />
PC using a serial link. In the Software Developer’s Kit, that device is a Smarthome<br />
PowerLinc V2 Controller with a USB or RS232 interface (see The Smarthome<br />
PowerLinc Controller and <strong>INSTEON</strong> BIOS).<br />
Serial communications can bridge networks of <strong>INSTEON</strong> devices to otherwise<br />
incompatible networks of devices in a home, to computers, to other nodes on a localarea<br />
network (LAN), or to the global Internet. Such connections to outside resources<br />
allow networks of <strong>INSTEON</strong> devices to exhibit complex, adaptive, people-pleasing<br />
behaviors. <strong>INSTEON</strong> devices capable of running downloadable SALad Applications<br />
(see SALad Language Documentation) can be upgraded to perform very<br />
sophisticated functions, including functions not envisioned at the time of<br />
manufacture or installation.<br />
October 14, 2005 © 2005 Smarthome Technology
<strong>INSTEON</strong> Message Repeating<br />
Developer’s <strong>Guide</strong> Page 20<br />
The figure below shows how network reliability improves when additional <strong>INSTEON</strong><br />
devices are added. The drawing shows <strong>INSTEON</strong> devices that communicate by<br />
powerline-only (PL), RF-only (RF), and both (RP).<br />
PL<br />
2A<br />
PL<br />
3A<br />
Powerline<br />
Phase A<br />
RF<br />
1<br />
PL<br />
1A<br />
PL<br />
4A<br />
RP<br />
1<br />
<strong>INSTEON</strong> Powerline Signal<br />
<strong>INSTEON</strong> RF Signal<br />
<strong>INSTEON</strong> RF Coverage<br />
RF<br />
2<br />
RF<br />
4<br />
RF<br />
PL<br />
RP<br />
RP<br />
2<br />
RF-only Device<br />
PL<br />
1B<br />
PL<br />
4B<br />
Powerline-only Device<br />
RF<br />
3<br />
RF / Powerline Hybrid Device<br />
PL<br />
2B<br />
PL<br />
3B<br />
Powerline<br />
Phase B<br />
Every <strong>INSTEON</strong> device is capable of repeating 1 <strong>INSTEON</strong> messages. They will do this<br />
automatically as soon as they are powered up—they do not need to be specially<br />
installed using some network setup procedure. Adding more devices increases the<br />
number of available pathways for messages to travel. This path diversity results in a<br />
higher probability that a message will arrive at its intended destination, so the more<br />
devices in an <strong>INSTEON</strong> network, the better.<br />
October 14, 2005 © 2005 Smarthome Technology
Developer’s <strong>Guide</strong> Page 21<br />
As an example, suppose RF device RF1 desires to send a message to RF3, but RF3 is<br />
out of range. The message will still get through, however, because devices within<br />
range of RF1, say RP1 and RF2, will receive the message and retransmit it to other<br />
devices within range of themselves. In the drawing, RP1 might reach RF2, RP2, and<br />
RF4, and devices RP2 and RF1 might be within range of the intended recipient, RF3.<br />
Therefore, there are many ways for a message to travel: RF1 to RF2 to RF3 (1<br />
retransmission), RF1 to RP1 to RP2 to RF3 (2 retransmissions), and RF1 to RP1 to<br />
RF2 to RP2 to RF3 (3 retransmissions) are some examples.<br />
On the powerline, path diversity has a similar beneficial effect. For example, the<br />
drawing shows powerline device PL1B without a direct communication path to device<br />
PL4B. In the real world, this might occur because of signal attenuation problems or<br />
because a direct path through the electric wiring does not exist. But a message from<br />
PL1B will still reach PL4B by taking a path through RP2 (1 retransmission), through<br />
PL2B to RP2 (2 retransmissions), or through PL2B to RP2 to PL3B (3<br />
retransmissions).<br />
The figure also shows how messages can travel among powerline devices that are<br />
installed on different phases of a home’s wiring. To accomplish phase bridging, at<br />
least one <strong>INSTEON</strong> hybrid RF/powerline device must be installed on each powerline<br />
phase. In the drawing, hybrid device RP1 is installed on phase A and RP2 is installed<br />
on phase B. Direct RF paths between RP1 to RP2, or indirect paths using RF2 or RF4<br />
(1 retransmission) allow messages to propagate between the powerline phases, even<br />
though there is no direct electrical connection.<br />
With all devices repeating messages, there must be some mechanism for limiting the<br />
number of times that a message may be retransmitted, or else messages might<br />
propagate forever within the network. Network saturation by repeating messages is<br />
known as a ‘data storm.’ The <strong>INSTEON</strong> protocol avoids this problem by limiting the<br />
maximum number times an individual message may be retransmitted to three (see<br />
<strong>INSTEON</strong> Message Hopping).<br />
October 14, 2005 © 2005 Smarthome Technology
<strong>INSTEON</strong> Peer-to-Peer Networking<br />
Developer’s <strong>Guide</strong> Page 22<br />
All <strong>INSTEON</strong> devices are peers, meaning that any device can act as a Controller<br />
(sending messages), Responder (receiving messages), or Repeater 1 (relaying<br />
messages).<br />
This relationship is illustrated in the figure below, where <strong>INSTEON</strong> device 1, acting as<br />
a Controller, sends messages to multiple <strong>INSTEON</strong> devices 2, 3, and 4 acting as<br />
Responders. Multiple <strong>INSTEON</strong> devices 5, 6, and 7 acting as Controllers can also<br />
send messages to a single <strong>INSTEON</strong> device 3 acting as a Responder.<br />
1<br />
Controller<br />
2<br />
Responder<br />
3<br />
Responder<br />
4<br />
Responder<br />
5<br />
Controller<br />
6<br />
Controller<br />
7<br />
Controller<br />
Any <strong>INSTEON</strong> device can repeat 1 messages, as with device B, below, which is shown<br />
relaying a message from device A acting as a Controller to device C acting as a<br />
Responder.<br />
A<br />
Controller<br />
B<br />
Repeater<br />
C<br />
Responder<br />
October 14, 2005 © 2005 Smarthome Technology
Developer’s <strong>Guide</strong> Page 23<br />
<strong>INSTEON</strong> Application Development<br />
Overview<br />
<strong>INSTEON</strong>, with its no-nonsense emphasis on simplicity, reliability, and low cost, is<br />
optimized as an infrastructure network. Common devices in the home, such as light<br />
switches, door locks, thermostats, clocks, and entertainment systems currently do<br />
not communicate with one another. <strong>INSTEON</strong> can change all that.<br />
When devices are networked together, there is a potential for coordinated, adaptive<br />
behavior that can bring a new, higher level of comfort, safety, and convenience to<br />
living. But networking devices together cannot by itself change the behavior of the<br />
devices. It is application-level software, created by developers, that transforms a<br />
network of previously unrelated devices into a coordinated, adaptive, lifestyleenhancing<br />
system.<br />
There are two basic kinds of applications that developers can create for <strong>INSTEON</strong>networked<br />
devices: External Applications and Internal Applications.<br />
External Applications run on a computing device such as a PC or PDA. A special<br />
type of <strong>INSTEON</strong> module called an <strong>INSTEON</strong> Bridge connects the computing device<br />
to an <strong>INSTEON</strong> network. Manager Apps are External Applications that exchange<br />
<strong>INSTEON</strong> messages directly with <strong>INSTEON</strong> devices via a Bridge.<br />
Internal Applications run on <strong>INSTEON</strong> devices themselves. Smarthome has<br />
developed an embedded language interpreter, called SALad, which resides in the<br />
firmware of SALad-enabled <strong>INSTEON</strong> devices. Developers can create and debug<br />
SALad Apps in a Smarthome Integrated Development Environment (IDE) that<br />
communicates with <strong>INSTEON</strong> devices via an <strong>INSTEON</strong> Bridge. Devices running<br />
SALad Apps can exhibit very sophisticated behavior. Moreover, devices that have<br />
already been installed in the home can be upgraded by downloading new SALad Apps<br />
to them. With <strong>INSTEON</strong> upgradeability, the world of home control can dynamically<br />
adapt to people’s expectations and needs as the marketplace evolves.<br />
In this section<br />
Interfacing to an <strong>INSTEON</strong> Network<br />
Describes <strong>INSTEON</strong> Bridge devices for connecting an <strong>INSTEON</strong> network to other<br />
devices, systems, or networks.<br />
Manager Applications<br />
Discusses <strong>INSTEON</strong> External Applications that send and receive <strong>INSTEON</strong><br />
messages directly.<br />
SALad Applications<br />
Explains how developers create <strong>INSTEON</strong> Internal Applications that run on<br />
SALad-enabled <strong>INSTEON</strong> devices themselves.<br />
<strong>INSTEON</strong> Developer’s Kits<br />
Describes the Software Developer’s Kit and various Hardware Development<br />
Modules available to designers of <strong>INSTEON</strong>-enabled products.<br />
October 14, 2005 © 2005 Smarthome Technology
Developer’s <strong>Guide</strong> Page 24<br />
Interfacing to an <strong>INSTEON</strong> Network<br />
An <strong>INSTEON</strong> device that connects an <strong>INSTEON</strong> network to the outside world is called<br />
an <strong>INSTEON</strong> Bridge. There can be many kinds of <strong>INSTEON</strong> Bridges. One kind, an<br />
<strong>INSTEON</strong>-to-Serial Bridge, connects an <strong>INSTEON</strong> network to a computing device like<br />
a PC, a PDA, or to a dedicated user interface device with a serial port. Another<br />
Bridge, <strong>INSTEON</strong>-to-IP, connects an <strong>INSTEON</strong> network to a LAN or the Internet,<br />
either with wires (like Ethernet) or wirelessly (like WiFi). Still other <strong>INSTEON</strong> Bridges<br />
could connect to other networks such as wired or wireless telephony, Bluetooth,<br />
ZigBee, WiMax, or whatever else emerges in the future.<br />
The Smarthome PowerLinc Controller<br />
The PowerLinc V2 Controller (PLC) from Smarthome is an example of an <strong>INSTEON</strong>to-Serial<br />
Bridge for connecting an <strong>INSTEON</strong> network to a computing device. PLCs<br />
are currently available with either a USB or an RS232 serial interface. An Ethernet<br />
interface, for connecting to a LAN or the Internet, is under development. For<br />
comprehensive information about the firmware capabilities of the PLC, see the<br />
<strong>INSTEON</strong> BIOS section below.<br />
Using the PLC, application developers can create high-level user interfaces to devices<br />
on an <strong>INSTEON</strong> network. Manager Apps are External Applications that run on a<br />
computing device and use the PLC to directly send and receive <strong>INSTEON</strong> messages<br />
to <strong>INSTEON</strong> devices. SALad Apps are Internal Applications that run on SALadenabled<br />
<strong>INSTEON</strong> devices themselves. The PLC is a SALad-enabled <strong>INSTEON</strong> device,<br />
having a SALad language interpreter embedded in its firmware.<br />
As shipped by Smarthome, the PLC contains a 1200-byte SALad coreApp Program<br />
that performs a number of useful functions:<br />
• When coreApp receives messages from <strong>INSTEON</strong> devices, it sends them to the<br />
computing device via its serial port, and when it receives <strong>INSTEON</strong>-formatted<br />
messages from the computing device via the serial port, it sends them out over<br />
the <strong>INSTEON</strong> network.<br />
• CoreApp handles linking to other <strong>INSTEON</strong> devices and maintains a Link<br />
Database.<br />
• CoreApp is event-driven, meaning that it can send messages to the computing<br />
device based on the time of day or other occurrences.<br />
• CoreApp can send and receive X10 commands.<br />
Source code for coreApp is available to developers to modify for their own purposes.<br />
Once programmed with an appropriately modified SALad App, the PLC can operate<br />
on its own without being connected to a computing device.<br />
As described in the section Masking Non-linked Network Traffic, the PLC hides the full<br />
addresses contained within <strong>INSTEON</strong> messages that it sees, unless the messages are<br />
from devices that it is already linked to. In particular, SALad Apps that the PLC may<br />
be running cannot discover the addresses of previously unknown <strong>INSTEON</strong> devices,<br />
so a hacker cannot write a SALad App that violates <strong>INSTEON</strong> security protocols.<br />
October 14, 2005 © 2005 Smarthome Technology
Manager Applications<br />
Developer’s <strong>Guide</strong> Page 25<br />
An <strong>INSTEON</strong> Manager App is an External Application program that runs on a<br />
computing device, like a PC or PDA, connected to an <strong>INSTEON</strong> network via an<br />
<strong>INSTEON</strong> Bridge. Manager Apps can provide sophisticated user interfaces for<br />
<strong>INSTEON</strong> devices, they can interact in complex ways with the outside world, and<br />
they can orchestrate system behaviors that bring real lifestyle benefits to people.<br />
A Manager App exchanges <strong>INSTEON</strong> messages directly with <strong>INSTEON</strong> devices, so it<br />
must contain a software module that can translate between a user’s intentions and<br />
the rules for composing and parsing <strong>INSTEON</strong> messages.<br />
An example of a Manager App that encapsulates these functions is Smarthome’s<br />
Device Manager (SDM) (see Smarthome Device Manager Reference), a Windows<br />
program that connects to an <strong>INSTEON</strong> network via a PowerLinc Controller (PLC).<br />
SDM handles all the intricacies involved with sending and receiving <strong>INSTEON</strong><br />
messages via a PLC. To the outside world, it exposes an interface that developers<br />
can connect their own custom top-level application layers to.<br />
This topmost layer, often a user interface, communicates with SDM using the<br />
Internet HTTP protocol or Microsoft’s ActiveX, so it can run on an Internet browser or<br />
within a Windows program. SDM and the top layer communicate using a simple<br />
text-based scripting language developed by Smarthome called Home Network<br />
Language (HNL).<br />
SDM allows designers to concentrate on rapid application development of their end<br />
products without having to deal directly with <strong>INSTEON</strong> messaging issues. Product<br />
developers are encouraged to contact Smarthome at info@insteon.net for more<br />
information about acquiring and using SDM.<br />
October 14, 2005 © 2005 Smarthome Technology
SALad Applications<br />
Developer’s <strong>Guide</strong> Page 26<br />
SALad is a language interpreter embedded in the firmware of SALad-enabled<br />
<strong>INSTEON</strong> devices (see SALad Overview). By writing and debugging SALad programs<br />
in Smarthome’s SALad Integrated Development Environment, developers can create<br />
<strong>INSTEON</strong> Internal Applications that run directly on SALad-enabled devices.<br />
SALad Overview<br />
Because the SALad instruction set is small and addressing modes for the instructions<br />
are highly symmetrical, SALad programs run fast and SALad object code is very<br />
compact.<br />
SALad is event driven. Events are triggered when a device receives an <strong>INSTEON</strong><br />
message, a user pushes a button, a timer expires, an X10 command is received, and<br />
so forth. As events occur, firmware in a SALad-enabled device posts event handles<br />
to an event queue, and then starts the SALad program. The SALad program<br />
determines what action to take based on the event that started it.<br />
SALad programs can be downloaded into nonvolatile memory of <strong>INSTEON</strong> devices<br />
using the <strong>INSTEON</strong> network itself, or via a serial link if the device has one. SALad<br />
also contains a small debugger that allows programs to be started, stopped, and<br />
single-stepped directly over the <strong>INSTEON</strong> network.<br />
SALad programming mostly consists of writing event handlers. By following<br />
examples in the <strong>INSTEON</strong> Software Development Kit, or by modifying Smarthome’s<br />
SALad coreApp Program, developers can rapidly create <strong>INSTEON</strong> devices with wideranging<br />
capabilities. For more information about the SALad Language, consult the<br />
SALad Language Documentation in this Developer’s <strong>Guide</strong>, or contact Smarthome at<br />
info@insteon.net.<br />
SALad Integrated Development Environment<br />
The SALad Integrated Development Environment (IDE) is a comprehensive, userfriendly<br />
tool for creating and debugging Internal Applications that run directly on<br />
SALad-enabled <strong>INSTEON</strong> devices. Using this tool, programmers can write, compile,<br />
download, and debug SALad programs without ever having to leave the IDE. The<br />
IDE is a Windows program that connects to an <strong>INSTEON</strong> network using a Smarthome<br />
PowerLinc Controller (see The Smarthome PowerLinc Controller).<br />
The SALad IDE includes:<br />
• A SALad Compiler that reads SALad language files and writes SALad object code,<br />
error listings, and variable maps<br />
• A communications module that can download SALad object code to an <strong>INSTEON</strong><br />
device via USB, RS232, or the <strong>INSTEON</strong> network itself<br />
• A multiple-file, color-contextual source code editor that automatically compiles<br />
SALad programs on the fly<br />
• Code templates for common tasks<br />
• A real-time debugger based upon instantaneous feedback from a SALad-enabled<br />
device<br />
• A program tracer<br />
October 14, 2005 © 2005 Smarthome Technology
Developer’s <strong>Guide</strong> Page 27<br />
• An interactive device conversation window for sending and receiving <strong>INSTEON</strong>,<br />
X10, or ASCII messages<br />
• A raw data window<br />
• A PLC simulator for writing and debugging SALad Apps without actually being<br />
connected to an <strong>INSTEON</strong> network<br />
• <strong>INSTEON</strong> device diagnostics<br />
• <strong>INSTEON</strong> network diagnostics<br />
• A device Link Database manager<br />
• A program listing formatter<br />
For complete information on installing and using the SALad IDE, consult the SALad<br />
Integrated Development Environment User’s <strong>Guide</strong> below.<br />
October 14, 2005 © 2005 Smarthome Technology
Developer’s <strong>Guide</strong> Page 28<br />
<strong>INSTEON</strong> SALad and PowerLinc Controller<br />
Architecture<br />
This diagram shows how software solutions can be implemented using The<br />
Smarthome PowerLinc Controller as an <strong>INSTEON</strong> gateway/controller device.<br />
October 14, 2005 © 2005 Smarthome Technology
<strong>INSTEON</strong> Developer’s Kits<br />
Developer’s <strong>Guide</strong> Page 29<br />
Smarthome is committed to making the development process as easy as possible for<br />
those who create products that can profit from <strong>INSTEON</strong> networking. For designers<br />
who will be crafting new <strong>INSTEON</strong> devices, adding <strong>INSTEON</strong> networking to existing<br />
devices, or developing External Applications for a network of <strong>INSTEON</strong> devices,<br />
Smarthome offers both a Software Developer’s Kit (SDK) and a series of Hardware<br />
Development Modules, as well as extensive technical support.<br />
Software Developer’s Kit<br />
To encourage as many developers as possible to join the community of <strong>INSTEON</strong><br />
product creators, Smarthome offers a comprehensive Software Developer’s Kit (SDK)<br />
for $99. The <strong>INSTEON</strong> SDK includes:<br />
• The <strong>INSTEON</strong> Integrated Development Environment (IDE)<br />
• A Smarthome PowerLinc V2 Controller (PLC) with either a USB or RS232 serial<br />
interface<br />
• A Smarthome LampLinc V2 Dimmer module<br />
• This <strong>INSTEON</strong> Developer’s <strong>Guide</strong> in both text and compiled help formats<br />
• Access to technical support and peer networking on the <strong>INSTEON</strong> Internet Forum<br />
• Source code to the SALad coreApp Program that runs on the PLC<br />
• Sample SALad Applications<br />
• Version maps for product upgrades<br />
• Header files<br />
Hardware Development Modules<br />
Smarthome will be releasing a series of Hardware Development Modules. The<br />
module that is currently available is an isolated powerline module ($99), to be<br />
followed soon by a non-isolated powerline module and an RF development module.<br />
The isolated powerline module is essentially a PowerLinc Controller (PLC) with an<br />
extender board that has a prototyping area and a hardware interface to internal<br />
circuitry, including the microcontroller. With this module, designers can build and<br />
debug hardware interfaces to controllers, sensors, or actuators that connect to an<br />
<strong>INSTEON</strong> network. The isolated power supply for this module ensures that no<br />
dangerous voltages are exposed.<br />
The non-isolated version of the powerline development module is only intended for<br />
those experts who are developing products that must achieve the lowest possible<br />
cost while still communicating over the powerline. To reduce the part count, the<br />
power supply is directly connected to the 110-volt mains, so potentially lethal<br />
voltages are exposed. Use of this module requires signing a liability waiver.<br />
The RF development module contains a special RF daughter board extending from a<br />
PLC. With this module, developers can create products that communicate via RF,<br />
and only optionally communicate via the powerline. RF-only devices can be battery<br />
operated, so this module is particularly designed with developers of handheld<br />
<strong>INSTEON</strong> devices in mind.<br />
October 14, 2005 © 2005 Smarthome Technology
<strong>INSTEON</strong> REFERENCE<br />
In This Section<br />
Developer’s <strong>Guide</strong> Page 30<br />
<strong>INSTEON</strong> Messages<br />
Gives the structure and contents of <strong>INSTEON</strong> messages and discusses message<br />
retransmission.<br />
<strong>INSTEON</strong> Signaling Details<br />
Explains how <strong>INSTEON</strong> messages are broken up into packets and transmitted<br />
over both the powerline and radio using synchronous simulcasting.<br />
<strong>INSTEON</strong> Network Usage<br />
Covers <strong>INSTEON</strong> Commands and Device Classes, explains how devices are<br />
logically linked together, and discusses <strong>INSTEON</strong> network security.<br />
<strong>INSTEON</strong> BIOS<br />
Documents the firmware running in the Smarthome PowerLinc V2 Controller<br />
(PLC).<br />
SALad Language Documentation<br />
Documents the SALad application programming language and commands.<br />
Smarthome Device Manager Reference<br />
Documents the Smarthome Device Manager and commands.<br />
<strong>INSTEON</strong> Hardware Development Documentation<br />
Describes the <strong>INSTEON</strong> Hardware Development Kit for powerline applications.<br />
October 14, 2005 © 2005 Smarthome Technology
<strong>INSTEON</strong> Messages<br />
Developer’s <strong>Guide</strong> Page 31<br />
<strong>INSTEON</strong> devices communicate by sending messages to one another. In the interest<br />
of maximum simplicity, there are only two kinds of <strong>INSTEON</strong> messages: 10-byte<br />
Standard messages and 24-byte Extended messages. The only difference between<br />
the two is that Extended messages carry 14 bytes of arbitrary User Data. They both<br />
carry a From Address, a To Address, a Flag byte, two Command bytes, and a<br />
Message Integrity byte.<br />
In this section<br />
<strong>INSTEON</strong> Message Structure<br />
Gives the details about the contents of the various fields in <strong>INSTEON</strong> messages.<br />
<strong>INSTEON</strong> Message Summary Table<br />
Gives a single table showing the usage of all of the fields in all possible <strong>INSTEON</strong><br />
message types. Recaps the usage of all of the different message types.<br />
<strong>INSTEON</strong> Message Repetition<br />
Explains how all <strong>INSTEON</strong> devices engage in retransmitting each other’s<br />
messages so that an <strong>INSTEON</strong> network will become more reliable as more<br />
devices are added.<br />
October 14, 2005 © 2005 Smarthome Technology
<strong>INSTEON</strong> Message Structure<br />
Developer’s <strong>Guide</strong> Page 32<br />
<strong>INSTEON</strong> devices communicate with each other by sending fixed-length messages.<br />
This section describes the two Message Lengths (Standard and Extended) and<br />
explains the contents of the Message Fields within the messages.<br />
Message Lengths<br />
There are only two kinds of <strong>INSTEON</strong> messages, 10-byte Standard Length Messages<br />
and 24-byte Extended Length Messages.<br />
The only difference between the two is that the Extended message contains 14 User<br />
Data Bytes not found in the Standard message. The remaining information fields for<br />
both types of message are identical.<br />
<strong>INSTEON</strong> Standard Message – 10 Bytes<br />
3 Bytes 3 Bytes 1 Byte 2 Bytes 1 Byte<br />
From Address To Address Flags Command 1, 2 CRC 3<br />
<strong>INSTEON</strong> Extended Message – 24 Bytes<br />
3 Bytes 3 Bytes 1 Byte 2 Bytes 14 Bytes 1 Byte<br />
From Address To Address Flags Command 1, 2 User Data CRC 3<br />
Standard Message<br />
Standard messages are designed for direct command and control. The payload is<br />
just two bytes, Command 1 and Command 2.<br />
Data Bits Contents<br />
From Address 24 Message Originator’s address<br />
To Address 24 For Direct messages:<br />
Intended Recipient’s address<br />
For Broadcast messages:<br />
Device Type, Subtype, Firmware Version<br />
For Group Broadcast messages:<br />
Group Number [0 - 255]<br />
1 Broadcast/NAK<br />
Message Type<br />
1 Group<br />
Message Flags<br />
Extended Flag<br />
1<br />
1<br />
Acknowledge<br />
0 (Zero) for Standard messages<br />
Hops Left 2 Counted down on each retransmission<br />
Max Hops 2 Maximum number of retransmissions allowed<br />
Command 1<br />
Command 2<br />
8<br />
8<br />
Command to execute<br />
CRC 3 8 Cyclic Redundancy Check<br />
October 14, 2005 © 2005 Smarthome Technology
Extended Message<br />
Developer’s <strong>Guide</strong> Page 33<br />
In addition to the same fields found in Standard messages, Extended messages carry<br />
14 bytes of arbitrary User Data for downloads, uploads, encryption, and advanced<br />
applications.<br />
Data Bits Contents<br />
From Address 24 Message Originator’s address<br />
To Address 24 For Direct messages:<br />
Intended Recipient’s address<br />
For Broadcast messages:<br />
Device Type, Subtype, Firmware Version<br />
For Group Broadcast messages:<br />
Group Number [0 - 255]<br />
Message Flags<br />
1 Broadcast/NAK<br />
Message Type<br />
1 Group<br />
1 Acknowledge<br />
Extended Flag 1 1 (One) for Extended messages<br />
Hops Left 2 Counted down on each retransmission<br />
Max Hops 2 Maximum number of retransmissions allowed<br />
Command 1<br />
Command 2<br />
8<br />
8<br />
Command to execute<br />
User Data 1 8<br />
User Data 2 8<br />
User Data 3 8<br />
User Data 4 8<br />
User Data 5 8<br />
User Data 6 8<br />
User Data 7<br />
User Data 8<br />
8<br />
8<br />
User defined data<br />
User Data 9 8<br />
User Data 10 8<br />
User Data 11 8<br />
User Data 12 8<br />
User Data 13 8<br />
User Data 14 8<br />
CRC 3 8 Cyclic Redundancy Check<br />
October 14, 2005 © 2005 Smarthome Technology
Message Fields<br />
Developer’s <strong>Guide</strong> Page 34<br />
All <strong>INSTEON</strong> messages contain source and destination Device Addresses, a Message<br />
Flags byte, a 2-byte Command 1 and 2 payload, and a Message Integrity Byte.<br />
<strong>INSTEON</strong> Extended messages also carry 14 bytes of User Data.<br />
Device Addresses<br />
The first field in an <strong>INSTEON</strong> message is the From Address, a 24-bit (3-byte) number<br />
that uniquely identifies the <strong>INSTEON</strong> device originating the message being sent.<br />
There are 16,777,216 possible <strong>INSTEON</strong> devices identifiable by a 3-byte number.<br />
This number can be thought of as an ID Code or, equivalently, as an address for an<br />
<strong>INSTEON</strong> device. During manufacture, a unique ID Code is stored in each device in<br />
nonvolatile memory.<br />
The second field in an <strong>INSTEON</strong> message is the To Address, also a 24-bit (3-byte)<br />
number. Most <strong>INSTEON</strong> messages are of the Direct, or Point-to-Point (P2P), type,<br />
where the intended recipient is another single, unique <strong>INSTEON</strong> device.<br />
If the message is indeed Direct (as determined by the Flags Byte), the To Address<br />
contains the 3-byte unique ID Code for the intended recipient. However, <strong>INSTEON</strong><br />
messages can also be sent to all recipients within range, as Broadcast messages, or<br />
they can be sent to all members of a group of devices, as Group Broadcast<br />
messages. In the case of Broadcast messages, the To Address field contains a 2byte<br />
Device Type and a Firmware Version byte. For Group Broadcast messages, the<br />
To Address field contains a Group Number. Group Numbers only range from 0 to<br />
255, given by one byte, so the two most-significant bytes of the three-byte field will<br />
be zero.<br />
Message Flags<br />
The third field in an <strong>INSTEON</strong> message, the Message Flags byte, not only signifies<br />
the Message Type but it also contains other information about the message. The<br />
three most-significant bits, the Broadcast/NAK flag (bit 7), the Group flag (bit 6),<br />
and the ACK flag (bit 5) together indicate the Message Type. Message Types will be<br />
explained in more detail in the next section (see Message Type Flags). Bit 4, the<br />
Extended flag, is set to one if the message is an Extended message, i.e. contains 14<br />
User Data bytes, or else it is set to zero if the message is a Standard message. The<br />
low nibble contains two two-bit fields, Hops Left (bits 3 and 2) and Max Hops (bits 1<br />
and 0). These two fields control message retransmission as explained below (see<br />
Message Retransmission Flags).<br />
The table below enumerates the meaning of the bit fields in the Message Flags byte.<br />
The Broadcast/NAK flag (bit 7, the most-significant byte), the Group flag (bit 6), and<br />
the ACK flag (bit 5) together denote the eight possible Message Types.<br />
October 14, 2005 © 2005 Smarthome Technology
Bit Position Flag Meaning<br />
Bit 7 (Broadcast /NAK)<br />
(MSB)<br />
Bit 6 (Group)<br />
Bit 5 (Acknowledge)<br />
Bit 4<br />
Bit 3<br />
Bit 2<br />
Bit 1<br />
Bit 0 (LSB)<br />
Developer’s <strong>Guide</strong> Page 35<br />
Message Type<br />
Extended<br />
Hops Left<br />
Max Hops<br />
Message Type Flags<br />
100 = Broadcast Message<br />
000 = Direct Message<br />
001 = ACK of Direct Message<br />
101 = NAK of Direct Message<br />
110 = Group Broadcast Message<br />
010 = Group Cleanup Direct Message<br />
011 = ACK of Group Cleanup Direct Message<br />
111 = NAK of Group Cleanup Direct Message<br />
1 = Extended Message<br />
0 = Standard Message<br />
00 = 0 message retransmissions remaining<br />
01 = 1 message retransmission remaining<br />
10 = 2 message retransmissions remaining<br />
11 = 3 message retransmissions remaining<br />
00 = Do not retransmit this message<br />
01 = Retransmit this message 1 time maximum<br />
10 = Retransmit this message 2 times maximum<br />
11 = Retransmit this message 3 times maximum<br />
There are eight possible <strong>INSTEON</strong> Message Types given by the three Message Type<br />
Flag Bits.<br />
Message Types<br />
To fully understand the eight Message Types, consider that there are four basic<br />
classes of <strong>INSTEON</strong> messages: Broadcast, Group Broadcast, Direct, and<br />
Acknowledge.<br />
Broadcast messages contain general information with no specific destination.<br />
Directed to the community of all devices within range, they are used extensively<br />
during device linking (see Device Identification Broadcast, below). Broadcast<br />
messages are not acknowledged.<br />
Group Broadcast messages are directed to a group of devices that have previously<br />
been linked to the message originator (see <strong>INSTEON</strong> Groups, below). Group<br />
Broadcast messages are not acknowledged directly. They only exist as a means for<br />
speeding up the response to a command intended for multiple devices. After<br />
sending a Group Broadcast message to a group of devices, the message originator<br />
then sends a Direct ‘Group Cleanup’ message to each member of the group<br />
individually, and waits for an acknowledgement back from each device.<br />
Direct messages, also referred to as Point-to-Point (P2P) messages, are intended<br />
for a single specific recipient. The recipient responds to Direct messages by<br />
returning an Acknowledge message.<br />
Acknowledge messages (ACK or NAK) are messages from the recipient to the<br />
message originator in response to a Direct message. There is no acknowledgement<br />
to a Broadcast or Group Broadcast message. An ACK or NAK message may contain<br />
status information from the acknowledging device.<br />
October 14, 2005 © 2005 Smarthome Technology
Message Type Flag Bits<br />
Developer’s <strong>Guide</strong> Page 36<br />
The Broadcast/NAK flag will be set whenever the message is a Broadcast message or<br />
a Group Broadcast message. In those two cases the Acknowledge flag will be clear.<br />
If the Acknowledge flag is set, the message is an Acknowledge message. In that<br />
case the Broadcast/NAK flag will be set when the Acknowledge message is a NAK,<br />
and it will be clear when the Acknowledge message is an ACK.<br />
The Group flag will be set to indicate that the message is a Group Broadcast<br />
message or part of a Group Cleanup conversation. This flag will be clear for general<br />
Broadcast messages and Direct conversations.<br />
Now all eight Message Types can be enumerated as follows, where the three-bit field<br />
is given in the order Bit 7, Bit 6, Bit 5.<br />
• Broadcast messages are Message Type 100.<br />
• Direct (P2P) messages are 000.<br />
• An ACK of a Direct message is 001<br />
• A NAK of a Direct message is 101<br />
• A Group Broadcast message is 110.<br />
• Group Broadcasts are followed up by a series of Group Cleanup Direct messages<br />
of Message Type 010 to each member of the group.<br />
• Each recipient of a Group Cleanup Direct message will return an<br />
acknowledgement with a Group Cleanup ACK of Message Type 011 or a Group<br />
Cleanup NAK of Message Type 111.<br />
Extended Message Flag<br />
Bit 4 is the Extended Message flag. This flag is set for 24-byte Extended messages<br />
that contain a 14-byte User Data field, and the flag is clear for 10-byte Standard<br />
messages that do not contain User Data.<br />
Message Retransmission Flags<br />
The remaining two flag fields, Max Hops and Hops Left, manage message<br />
retransmission. As described above, all <strong>INSTEON</strong> devices are capable of repeating 1<br />
messages by receiving and retransmitting them. Without a mechanism for limiting<br />
the number of times a message can be retransmitted, an uncontrolled ‘data storm’ of<br />
endlessly repeated messages could saturate the network. To solve this problem,<br />
<strong>INSTEON</strong> message originators set the 2-bit Max Hops field to a value of 0, 1, 2, or 3,<br />
and they also set the 2-bit Hops Left field to the same value. A Max Hops value of<br />
zero tells other devices within range not to retransmit the message. A higher Max<br />
Hops value tells devices receiving the message to retransmit it depending on the<br />
Hops Left field. If the Hops Left value is one or more, the receiving device<br />
decrements the Hops Left value by one, then retransmits the message with the new<br />
Hops Left value. Devices that receive a message with a Hops Left value of zero will<br />
not retransmit that message. Also, a device that is the intended recipient of a<br />
message will not retransmit the message, no matter what the Hops Left value is.<br />
See <strong>INSTEON</strong> Message Hopping for more information.<br />
Note that the designator ‘Max Hops’ really means maximum retransmissions allowed.<br />
All <strong>INSTEON</strong> messages ‘hop’ at least once, so the value in the Max Hops field is one<br />
less than the number of times a message actually hops from one device to another.<br />
Since the maximum value in this field is three, there can be four actual hops,<br />
October 14, 2005 © 2005 Smarthome Technology
Developer’s <strong>Guide</strong> Page 37<br />
consisting of the original transmission and three retransmissions. Four hops can<br />
span a chain of five devices. This situation is shown schematically below.<br />
Device Number 1 2 3 4 5<br />
Max Hops 3 3 3 3 3<br />
Hops Left 3 3 → 2 2 → 1 1 → 0 0<br />
<br />
Hop Number 1 2 3 4<br />
Retransmission Number 0 1 2 3<br />
Command 1 and 2<br />
The fourth field in an <strong>INSTEON</strong> message is a two-byte Command, made up of<br />
Command 1 and Command 2. The usage of this field depends on the Message Type<br />
as explained below (see <strong>INSTEON</strong> Commands).<br />
User Data<br />
Only if the message is an Extended message, with the Extended Flag set to one, will<br />
it contain the fourteen-byte User Data field. User Data can be arbitrarily defined.<br />
If more than 14 bytes of User Data need to be transmitted, multiple <strong>INSTEON</strong><br />
Extended messages will have to be sent. Users can define a packetizing method for<br />
their data so that a receiving device can reliably reassemble long messages.<br />
Encrypting User Data can provide private, secure communications for sensitive<br />
applications such as security systems. See <strong>INSTEON</strong> Extended Messages, below, for<br />
more information.<br />
Message Integrity Byte<br />
The last field in an <strong>INSTEON</strong> message is a one-byte CRC, or Cyclic Redundancy<br />
Check. The <strong>INSTEON</strong> transmitting device computes the CRC over all the bytes in a<br />
message beginning with the From Address. <strong>INSTEON</strong> uses a software-implemented<br />
7-bit linear-feedback shift register with taps at the two most-significant bits. The<br />
CRC covers 9 bytes for Standard messages and 23 bytes for Extended messages. An<br />
<strong>INSTEON</strong> receiving device computes its own CRC over the same message bytes as it<br />
receives them. If the message is corrupt, the receiver’s CRC will not match the<br />
transmitted CRC.<br />
Firmware in the <strong>INSTEON</strong> Engine handles the CRC byte automatically, appending it<br />
to messages that it sends, and comparing it within messages that it receives.<br />
Applications post messages to and receive messages from the <strong>INSTEON</strong> Engine<br />
without the CRC byte being appended.<br />
Detection of message integrity allows for highly reliable, verified communications.<br />
The <strong>INSTEON</strong> ACK/NAK (acknowledge, non-acknowledge) closed-loop messaging<br />
protocol based on this detection method is described below (see <strong>INSTEON</strong> Message<br />
Retrying).<br />
October 14, 2005 © 2005 Smarthome Technology
Developer’s <strong>Guide</strong> Page 38<br />
<strong>INSTEON</strong> Message Summary Table<br />
The table below summarizes all the fields in every type of <strong>INSTEON</strong> message.<br />
Standard messages are enumerated at the top and Extended messages are<br />
enumerated at the bottom. The figure clearly shows that the only difference<br />
between Standard and Extended messages is that the Extended Flag is clear for<br />
Standard messages and set for Extended messages, and Extended messages<br />
possess a 14-byte User Data field. The From Address, the To Address, the Message<br />
Flags, and the CRCs are as explained above.<br />
Message<br />
Standard<br />
Extended<br />
3 Bytes 3 Bytes 1 Byte 1 Byte 1 Byte 1 Byte<br />
From Address To Address<br />
Message Flags<br />
Type X HL MH<br />
Cmd 1 Cmd 2 CRC3<br />
Broadcast ID1_2 ID1_1 ID1_0 Device Type Revision 1 0 0 0 Broadcast Cmd CRC<br />
Broadcast Group ID1_2 ID1_1 ID1_0 0 0 Group # 1 1 0 0 Gp Cmd Param CRC<br />
P2P Cleanup ID1_2 ID1_1 ID1_0 ID2_2 ID2_1 ID2_0 0 1 0 0 Gp Cmd Group # CRC<br />
P2P Cleanup ACK ID1_2 ID1_1 ID1_0 ID2_2 ID2_1 ID2_0 0 1 1 0 Gp Cmd Status CRC<br />
P2P Cleanup NAK ID1_2 ID1_1 ID1_0 ID2_2 ID2_1 ID2_0 1 1 1 0 Gp Cmd Reason CRC<br />
P2P ID1_2 ID1_1 ID1_0 ID2_2 ID2_1 ID2_0 0 0 0 0 Direct Cmd CRC<br />
P2P ACK ID1_2 ID1_1 ID1_0 ID2_2 ID2_1 ID2_0 0 0 1 0 ACK Status CRC<br />
P2P NAK ID1_2 ID1_1 ID1_0 ID2_2 ID2_1 ID2_0 1 0 1 0 NAK Reason CRC<br />
14 Bytes 1 Byte<br />
D1 ⇒ D14 CRC 3<br />
Broadcast ID1_2 ID1_1 ID1_0 Device Type Revision 1 0 0 1 Broadcast Cmd D1 ⇒ D14 CRC<br />
Broadcast Group ID1_2 ID1_1 ID1_0 0 0 Group # 1 1 0 1 Gp Cmd Param D1 ⇒ D14 CRC<br />
P2P Cleanup ID1_2 ID1_1 ID1_0 ID2_2 ID2_1 ID2_0 0 1 0 1 Gp Cmd Group # D1 ⇒ D14 CRC<br />
P2P Cleanup ACK ID1_2 ID1_1 ID1_0 ID2_2 ID2_1 ID2_0 0 1 1 1 Gp Cmd Status D1 ⇒ D14 CRC<br />
P2P Cleanup NAK ID1_2 ID1_1 ID1_0 ID2_2 ID2_1 ID2_0 1 1 1 1 Gp Cmd Reason D1 ⇒ D14 CRC<br />
P2P ID1_2 ID1_1 ID1_0 ID2_2 ID2_1 ID2_0 0 0 0 1 Direct Cmd D1 ⇒ D14 CRC<br />
P2P ACK ID1_2 ID1_1 ID1_0 ID2_2 ID2_1 ID2_0 0 0 1 1 ACK Status D1 ⇒ D14 CRC<br />
P2P NAK ID1_2 ID1_1 ID1_0 ID2_2 ID2_1 ID2_0 1 0 1 1<br />
NAK Reason D1 ⇒ D14 CRC<br />
The Command 1 and Command 2 fields contain different information for each of the<br />
eight types of <strong>INSTEON</strong> messages. In the case of Broadcast messages, the two<br />
fields together contain a 2-byte command chosen from a possible 65,536 commands<br />
suitable for sending to all devices at once. For example, a device can identify itself<br />
to other devices by sending a SET Button Pushed Broadcast command (see Device<br />
Identification Broadcast). Every receiving device contains a database of Broadcast<br />
commands that it is capable of executing.<br />
In the case of Point-to-Point (Direct) messages, the two Command fields together<br />
comprise a 2-byte command chosen from a possible 65,536 commands suitable for<br />
sending to a single device. For example, a Direct command could tell a lamp control<br />
device to turn on the lamp plugged into it. Every receiving device contains a<br />
database of Direct commands that it is capable of executing (see <strong>INSTEON</strong><br />
Commands).<br />
In the interest of maximum system reliability, the <strong>INSTEON</strong> protocol requires that<br />
Direct messages be acknowledged. A receiving device can issue an<br />
acknowledgement of successful communication and completion of a task, i.e. an<br />
ACK, or it can issue a NAK to indicate some kind of failure. If a receiving device fails<br />
to send an ACK or a NAK back to the originating device, the originating device will<br />
retry the message (see <strong>INSTEON</strong> Message Retrying).<br />
October 14, 2005 © 2005 Smarthome Technology<br />
Group<br />
Broadcast / NAK<br />
Extended<br />
Acknowledge<br />
Message retransmissions left<br />
Hops Left, 2 bits<br />
Maximum message retransmissions allowed<br />
Max Hops, 2 bits
Developer’s <strong>Guide</strong> Page 39<br />
To respond with an ACK or a NAK, firmware in a receiving device swaps the From<br />
Address and the To Address in the message it received, and sets the Message Type<br />
bits to 001 for an ACK or 101 for a NAK. Depending on the command received in the<br />
Command fields, the receiving device composes a two-byte status response code for<br />
an ACK or else a two-byte reason code for a NAK, which it inserts in the Command<br />
fields. For example, if a lamp dimmer receives a command to set the lamp to a<br />
certain brightness level, issued as a Set Brightness code in the Command 1 field and<br />
the desired brightness level as one of 256 values in the Command 2 field, the<br />
dimmer will respond with an ACK message containing the same two bytes in the<br />
Command fields to indicate successful execution of the command.<br />
The remaining <strong>INSTEON</strong> message types are for dealing with groups of devices (see<br />
<strong>INSTEON</strong> Groups). Group Broadcast messages exist as a performance enhancement.<br />
While it is true that all the members of a group of devices could be sent individual<br />
Direct messages with the same command (to turn on, for example), it would take a<br />
noticeable amount of time for all the messages to be transmitted in sequence. The<br />
members of the group would not execute the command all at once, but rather in the<br />
order received. <strong>INSTEON</strong> solves this problem by first sending a Group Broadcast<br />
message, then following it up with individual Direct ‘Group Cleanup’ messages.<br />
Group Broadcast messages contain a Group Number in the To Address field, a onebyte<br />
Group Command in the Command 1 field, and an optional one-byte parameter<br />
in the Command 2 field. During the Direct Group Cleanup messages that will follow,<br />
the Group Command will be sent in the Command 1 field and the Group Number will<br />
be sent in the Command 2 field. These are both one-byte fields, so there can only<br />
be 256 Group Commands and only 256 Group Numbers. This is a reasonable<br />
limitation given that Group Broadcasts only need to be used where rapid,<br />
synchronous response of multiple devices is an issue. In any case, the numerical<br />
limitation can be overcome by using Extended messages and embedding additional<br />
commands or group membership criteria in the User Data field.<br />
Recipients of a Group Broadcast message check the Group Number in the To Address<br />
field against their own group memberships recorded in a Link Database (see<br />
<strong>INSTEON</strong> Link Database). This database, stored in nonvolatile memory, is<br />
established during a prior group enrollment, or linking, process (see Methods for<br />
Linking <strong>INSTEON</strong> Devices). If the recipient is a member of the Group being<br />
broadcast to, it executes the command in the Command 1 field. Since the Group<br />
Command only occupies one byte, the other byte in field can be a parameter or a<br />
subcommand.<br />
Group Broadcast command recipients can expect a Direct individually-addressed<br />
Group Cleanup message to follow. If the recipient has already executed the Group<br />
Command, it will not execute the command a second time. However, if the recipient<br />
missed the Group Broadcast command for any reason, it will not have executed it, so<br />
it will execute the command after receiving the Direct Group Cleanup message.<br />
After receiving the Direct Group Cleanup message and executing the Group<br />
Command, the recipient device will respond with a Group Cleanup ACK message, or<br />
else, if something went wrong, it will respond with a Group Cleanup NAK message.<br />
In both cases the Command 1 field will contain the same one-byte Group Command<br />
received during the Direct Group Cleanup message. The other byte in the Command<br />
2 field will contain a one-byte ACK Status code in the case of an ACK, or a one-byte<br />
NAK Reason code in the case of a NAK. These one-byte codes are a subset of the<br />
corresponding two-byte codes used in Direct ACK and Direct NAK messages.<br />
October 14, 2005 © 2005 Smarthome Technology
<strong>INSTEON</strong> Message Repetition<br />
Developer’s <strong>Guide</strong> Page 40<br />
To maximize communications reliability, the <strong>INSTEON</strong> messaging protocol includes<br />
two kinds of message repetition: message hopping and message retrying.<br />
<strong>INSTEON</strong> Message Hopping is the mechanism whereby <strong>INSTEON</strong> devices, all of which<br />
can retransmit <strong>INSTEON</strong> messages, aid each other in delivering a message from a<br />
message originator to a message recipient.<br />
<strong>INSTEON</strong> Message Retrying occurs when the originator of a Direct message does not<br />
receive a proper acknowledgement message from the intended recipient.<br />
<strong>INSTEON</strong> Message Hopping<br />
In order to improve reliability, the <strong>INSTEON</strong> messaging protocol includes message<br />
retransmission, or hopping. Hopping enables other <strong>INSTEON</strong> devices, all of which<br />
can repeat 1 messages, to help relay a message from an originator to a recipient.<br />
When <strong>INSTEON</strong> devices repeat messages, multiple devices can end up simulcasting<br />
the same message, meaning that they can repeat the same message at the same<br />
time. To ensure that simulcasting is synchronous (so that multiple devices do not<br />
jam each other), <strong>INSTEON</strong> devices adhere to specific rules given below (see Timeslot<br />
Synchronization).<br />
Message Hopping Control<br />
Two 2-bit fields in the Message Flags byte manage <strong>INSTEON</strong> message hopping (see<br />
Message Retransmission Flags, above). One field, Max Hops, contains the maximum<br />
number of hops, and the other, Hops Left, contains the number of hops remaining.<br />
To avoid ‘data storms’ of endless repetition, messages can be retransmitted a<br />
maximum of three times only. A message originator sets the Max Hops for a<br />
message. The larger the number of Max Hops, the longer the message will take to<br />
complete being sent, whether or not the recipient hears the message early.<br />
If the Hops Left field in a message is nonzero, every device that hears the message<br />
synchronously repeats it, thus increasing the signal strength, path diversity, and<br />
range of the message. An <strong>INSTEON</strong> device that repeats a message decrements Hops<br />
Left before retransmitting it. When a device receives a message with zero Hops Left,<br />
it does not retransmit the message.<br />
Timeslot Synchronization<br />
There is a specific pattern of transmissions, retransmissions and acknowledgements<br />
that occurs when an <strong>INSTEON</strong> message is sent, as shown in the examples below.<br />
An <strong>INSTEON</strong> message on the powerline occupies either six or thirteen zero crossing<br />
periods, depending on whether the message is Standard or Extended. This message<br />
transmission time, six or thirteen powerline half-cycles, is called a timeslot in the<br />
following discussion.<br />
During a single timeslot, an <strong>INSTEON</strong> message can be transmitted, retransmitted, or<br />
acknowledged. The entire process of communicating an <strong>INSTEON</strong> message, which<br />
may involve retransmissions and acknowledgements, will occur over integer<br />
multiples of timeslots.<br />
October 14, 2005 © 2005 Smarthome Technology
Developer’s <strong>Guide</strong> Page 41<br />
The following examples show how <strong>INSTEON</strong> messages propagate in a number of<br />
common scenarios. The examples use these symbols:<br />
Legend<br />
T Transmission by Message Originator<br />
R Message Retransmission<br />
A Acknowledgement by Intended Recipient<br />
C Confirmation received by Message Originator<br />
L Listening State<br />
W Waiting State<br />
Max<br />
Hops<br />
Timeslot 1 2 3 4 5 6 7 8<br />
Example 1 0 Sender T<br />
Example 1, the simplest, shows a Broadcast message with a Max Hops of zero (no<br />
retransmissions). The T indicates that the Sender has originated and transmitted a<br />
single message. There is no acknowledgement that intended recipients have heard<br />
the message. The message required one timeslot of six or thirteen powerline zero<br />
crossings to complete.<br />
Max<br />
Hops<br />
Example 2 1<br />
Timeslot 1 2 3 4 5 6 7 8<br />
Sender T<br />
Repeater 1 L R<br />
Example 2 shows a Broadcast message with a Max Hops of one. Max Hops can<br />
range from zero to three as explained above. The Sender transmits a Broadcast<br />
message as signified by the T. Another <strong>INSTEON</strong> device, functioning as a Repeater,<br />
listens to the message, as signified by an L, and then retransmits it in the next<br />
timeslot as indicated by the R.<br />
Max<br />
Hops<br />
Example 3 3<br />
Timeslot 1 2 3 4 5 6 7 8<br />
Sender T L L L L<br />
Repeater 1 L R L R L<br />
Repeater 2 L L R L L<br />
Repeater 3 L L L R L<br />
Up to three retransmissions are possible with a message. Example 3 shows the<br />
progression of the message involving an originating Sender and three repeating<br />
devices, with a Max Hops of three. Example 3 assumes that the range between<br />
Repeaters is such that only adjacent Repeaters can hear each other, and that only<br />
Repeater 1 can hear the Sender. Note that the Sender will not retransmit its own<br />
message.<br />
October 14, 2005 © 2005 Smarthome Technology
Max<br />
Hops<br />
Example 4 0<br />
Developer’s <strong>Guide</strong> Page 42<br />
Timeslot 1 2 3 4 5 6 7 8<br />
Sender T C<br />
Recipient L A<br />
When a Sender transmits a Direct (Point-to-Point) message, it expects an<br />
acknowledgement from the Recipient. Example 4 shows what happens if the Max<br />
Hops value is zero. The A designates the timeslot in which the Recipient<br />
acknowledges receipt of the Direct message. The C shows the timeslot when the<br />
Sender finds that the message is confirmed.<br />
Max<br />
Hops<br />
Example 5 1<br />
Timeslot 1 2 3 4 5 6 7 8<br />
Sender T L L C<br />
Repeater 1 L R L R<br />
Recipient L L A L<br />
When Max Hops is set to one, a Direct message propagates as shown in Example 5.<br />
Repeater 1 will retransmit both the original Direct message and the<br />
acknowledgement from the Recipient.<br />
Max<br />
Hops<br />
Example 6 1<br />
Timeslot 1 2 3 4 5 6 7 8<br />
Sender T L C W<br />
Repeater 1 L R L R<br />
Recipient L W A L<br />
If Max Hops is set to one, but no retransmission is needed because the Recipient is<br />
within range of the Sender, messages flow as shown in Example 6. The W in the<br />
Sender and Recipient rows indicates a wait. The Recipient immediately hears the<br />
Sender since it is within range. However, the Recipient must wait one timeslot<br />
before sending its acknowledgement, because it is possible that a repeating device<br />
will be retransmitting the Sender’s message. Repeater 1 is shown doing just that in<br />
the example, although the Recipient would still have to wait even if no Repeaters<br />
were present. Only when all of the possible retransmissions of the Sender’s message<br />
are complete, can the Recipient send its acknowledgement. Being within range, the<br />
Sender hears the acknowledgement immediately, but it must also wait until possible<br />
retransmissions of the acknowledgement are finished before it can send another<br />
message.<br />
October 14, 2005 © 2005 Smarthome Technology
Max<br />
Hops<br />
Example 7 3<br />
Developer’s <strong>Guide</strong> Page 43<br />
Timeslot 1 2 3 4 5 6 7 8<br />
Sender T L L L L L L C<br />
Repeater 1 L R L R L R L R<br />
Repeater 2 L L R L L L R L<br />
Repeater 3 L L L R L R L R<br />
Recipient L L L L A L R L<br />
Example 7 shows what happens when Max Hops is three and three retransmissions<br />
are in fact needed for the message to reach the Recipient. Note that if the Sender or<br />
Recipient were to hear the other’s message earlier than shown, it still must wait until<br />
Max Hops timeslots have occurred after the message was originated before being<br />
free to send its own message. If devices did not wait, they would jam each other by<br />
sending different messages in the same timeslot. A device can calculate how many<br />
timeslots have passed prior to receiving a message by subtracting the Hops Left<br />
number in the received message from the Max Hops number.<br />
October 14, 2005 © 2005 Smarthome Technology
Developer’s <strong>Guide</strong> Page 44<br />
All seven of the above examples are given again in the table below in order to show<br />
the patterns more clearly.<br />
Max<br />
Hops<br />
Example 1 0 Sender T<br />
Example 2 1<br />
Example 3 3<br />
Example 4 0<br />
Example 5 1<br />
Example 6 1<br />
Example 7 3<br />
Legend<br />
Timeslot 1 2 3 4 5 6 7 8<br />
Sender T<br />
Repeater 1 L R<br />
Sender T L L L L<br />
Repeater 1 L R L R L<br />
Repeater 2 L L R L L<br />
Repeater 3 L L L R L<br />
Sender T C<br />
Recipient L A<br />
Sender T L L C<br />
Repeater 1 L R L R<br />
Recipient L L A L<br />
Sender T L C W<br />
Repeater 1 L R L R<br />
Recipient L W A L<br />
Sender T L L L L L L C<br />
Repeater 1 L R L R L R L R<br />
Repeater 2 L L R L L L R L<br />
Repeater 3 L L L R L R L R<br />
Recipient L L L L A L R L<br />
T Transmission by Message Originator<br />
R Message Retransmission<br />
A Acknowledgement by Intended Recipient<br />
C Confirmation received by Message Originator<br />
L Listening State<br />
W Waiting State<br />
October 14, 2005 © 2005 Smarthome Technology
<strong>INSTEON</strong> Message Retrying<br />
Developer’s <strong>Guide</strong> Page 45<br />
If the originator of an <strong>INSTEON</strong> Direct message does not receive an<br />
acknowledgement from the intended recipient, the message originator will<br />
automatically try resending the message up to five times.<br />
In case a message did not get through because Max Hops was set too low, each time<br />
the message originator retries a message, it also increases Max Hops up to the limit<br />
of three. A larger number of Max Hops can achieve greater range for the message<br />
by allowing more devices to retransmit it.<br />
Firmware in the <strong>INSTEON</strong> Engine handles message retrying. After using the<br />
<strong>INSTEON</strong> Engine to send a Direct message, applications will either receive the<br />
expected acknowledgement message or an indication that the intended recipient did<br />
not receive the Direct message after five retries.<br />
Because message retrying is automatic, it is important to unlink <strong>INSTEON</strong> Responder<br />
devices from <strong>INSTEON</strong> Controller devices when a linked device is removed from an<br />
<strong>INSTEON</strong> network. See <strong>INSTEON</strong> Link Database, below, for more information.<br />
October 14, 2005 © 2005 Smarthome Technology
<strong>INSTEON</strong> Signaling Details<br />
Developer’s <strong>Guide</strong> Page 46<br />
This section gives complete information about how the data in <strong>INSTEON</strong> messages<br />
actually travels over the powerline or the airwaves. Unlike other mesh networks,<br />
<strong>INSTEON</strong> does not elaborately route its traffic in order to avoid data collisions—<br />
instead, <strong>INSTEON</strong> devices simulcast according to simple rules explained below.<br />
Simulcasting by multiple devices is made possible because <strong>INSTEON</strong> references a<br />
global clock, the powerline zero crossing.<br />
In this section<br />
<strong>INSTEON</strong> Packet Structure<br />
Shows how messages are packetized for powerline and RF transmission.<br />
<strong>INSTEON</strong> Signaling<br />
Covers bit encoding for powerline and RF transmission, packet synchronizing,<br />
X10 compatibility 2 , message timeslots, and data rates.<br />
Simulcasting<br />
Explains how allowing multiple <strong>INSTEON</strong> devices to talk at the same time makes<br />
an <strong>INSTEON</strong> network more reliable as more devices are added, and eliminates<br />
the need for complex, costly message routing.<br />
October 14, 2005 © 2005 Smarthome Technology
<strong>INSTEON</strong> Packet Structure<br />
This section describes Powerline Packets and RF Packets.<br />
Powerline Packets<br />
Developer’s <strong>Guide</strong> Page 47<br />
Messages sent over the powerline are broken up into packets, with each packet sent<br />
in conjunction with a zero crossing of the AC voltage on the powerline. Standard<br />
Messages use five packets and Extended Messages use eleven packets, as shown<br />
below.<br />
Standard Message – 5 Packets<br />
SP BP BP BP BP<br />
Extended Message - 11 Packets<br />
120 total bits = 15 bytes<br />
84 Data bits = 10½ bytes, 10 usable<br />
264 total bits = 33 bytes<br />
192 Data bits = 24 bytes<br />
SP BP BP BP BP BP BP BP BP BP BP<br />
A Start Packet appears as the first packet in an <strong>INSTEON</strong> message, as shown by the<br />
symbol SP in both the Standard and Extended Messages. The remaining packets in<br />
a message are Body Packets, as shown by the symbols BP.<br />
Each packet contains 24 bits of information, but the information is interpreted in two<br />
different ways, as shown below.<br />
SP Start Packet<br />
1 0 1 0 1 0 1 0 1 0 0 1 x x x x x x x x x x x x<br />
8 Sync bits<br />
BP Body Packet<br />
4 Start Code<br />
bits<br />
12 Data bits<br />
1 0 1 0 0 1 x x x x x x x x x x x x x x x x x x<br />
2 Sync<br />
bits<br />
4 Start Code<br />
bits<br />
18 Data Bits<br />
Powerline packets begin with a series of Sync Bits. There are eight Sync Bits in a<br />
Start Packet and there are two Sync Bits in a Body Packet. The alternating pattern<br />
of ones and zeros allows the receiver to detect the presence of a signal.<br />
Following the Sync Bits are four Start Code Bits. The 1001 pattern indicates to the<br />
receiver that Data bits will follow.<br />
October 14, 2005 © 2005 Smarthome Technology
Developer’s <strong>Guide</strong> Page 48<br />
The remaining bits in a packet are Data Bits. There are twelve Data Bits in a Start<br />
Packet, and there are eighteen Data Bits in a Body Packet.<br />
The total number of Data Bits in a Standard Message is 84, or 10½ bytes. The last<br />
four data bits in a Standard Message are ignored, so the usable data is 10 bytes.<br />
The total number of Data Bits in an Extended Message is 192, or 24 bytes.<br />
RF Packets<br />
The figure below shows the contents of <strong>INSTEON</strong> messages sent using RF. Because<br />
<strong>INSTEON</strong> RF messaging is much faster than powerline messaging, there is no need<br />
to break up RF messages into smaller packets. An RF Standard message and an RF<br />
Extended message are both shown. In both cases the message begins with two<br />
Sync Bytes followed by one Start Code Byte. RF Standard messages contain 10 Data<br />
Bytes (80 bits), and RF Extended messages contain 24 Data Bytes (192 bits).<br />
RF Standard Message – 1 Packet<br />
AA AA C3 x x x x x x x x x x n<br />
2<br />
Sync<br />
bytes<br />
1<br />
Start<br />
Code<br />
byte<br />
80 Data Bits (10 Data bytes) CRC 3<br />
RF Extended Message – 1 Packet<br />
112 total bits = 14 bytes<br />
80 Data bits = 10 bytes<br />
224 total bits = 28 bytes<br />
192 Data bits = 24 bytes<br />
AA AA C3 x x x x x x x x x x x x x x x x x x x x x x x x n<br />
2<br />
Sync<br />
bytes<br />
1<br />
Start<br />
Code<br />
byte<br />
192 Data Bits (24 Data bytes) CRC 3<br />
October 14, 2005 © 2005 Smarthome Technology
<strong>INSTEON</strong> Signaling<br />
Developer’s <strong>Guide</strong> Page 49<br />
This section explains bit encoding for powerline and RF transmission, packet<br />
synchronization to the powerline, X10 compatibility 2 , message timeslots, and data<br />
rates.<br />
Powerline Signaling<br />
<strong>INSTEON</strong> devices communicate on the powerline by adding a signal to the powerline<br />
voltage. In the United States, powerline voltage is nominally 110 VAC RMS,<br />
alternating at 60 Hz.<br />
An <strong>INSTEON</strong> powerline signal uses a carrier frequency of 131.65 KHz, with a nominal<br />
amplitude of 4.64 volts peak-to-peak into a 5 ohm load. In practice, the impedance<br />
of powerlines varies widely, depending on the powerline configuration and what is<br />
plugged into it, so measured <strong>INSTEON</strong> powerline signals can vary from sub-millivolt<br />
to more than 5 volts.<br />
<strong>INSTEON</strong> data is modulated onto the 131.65 KHz carrier using binary phase-shift<br />
keying, or BPSK, chosen for reliable performance in the presence of noise.<br />
The bytes in an <strong>INSTEON</strong> powerline message are transmitted most-significant byte<br />
first, and the bits are transmitted most-significant bit first.<br />
October 14, 2005 © 2005 Smarthome Technology
BPSK Modulation<br />
Developer’s <strong>Guide</strong> Page 50<br />
The figure below shows an <strong>INSTEON</strong> 131.65 KHz powerline carrier signal with<br />
alternating binary phase-shift keying (BPSK) bit modulation.<br />
Bit 1<br />
1<br />
Bit 2<br />
0<br />
<strong>INSTEON</strong> uses 10 cycles of carrier for each bit. Bit 1, interpreted as a one, begins<br />
with a positive-going carrier cycle. Bit 2, interpreted as a zero, begins with a<br />
negative-going carrier cycle. Bit 3 begins with a positive-going carrier cycle, so it is<br />
interpreted as a one. Note that the sense of the bit interpretations is arbitrary. That<br />
is, ones and zeros could be reversed as long as the interpretation is consistent.<br />
Phase transitions only occur when a bitstream changes from a zero to a one or from<br />
a one to a zero. A one followed by another one, or a zero followed by another zero,<br />
will not cause a phase transition. This type of coding is known as NRZ, or non-return<br />
to zero.<br />
Note the abrupt phase transitions of 180 degrees at the bit boundaries. Abrupt<br />
phase transitions introduce troublesome high-frequency components into the signal’s<br />
spectrum. Phase-locked detectors can have trouble tracking such a signal. To solve<br />
this problem, <strong>INSTEON</strong> uses a gradual phase change to reduce the unwanted<br />
frequency components.<br />
Bit 1<br />
1<br />
Bit 2<br />
0<br />
The figure above shows the same BPSK signal with gradual phase shifting. The<br />
transmitter introduces the phase change by inserting 1.5 cycles of carrier at 1.5<br />
times the 131.65 KHz frequency. Thus, in the time taken by one cycle of 131.65<br />
KHz, three half-cycles of carrier will have occurred, so the phase of the carrier will be<br />
reversed at the end of the period due to the odd number of half-cycles. Note the<br />
smooth transitions between the bits.<br />
October 14, 2005 © 2005 Smarthome Technology<br />
Bit 3<br />
1<br />
Bit 3<br />
1
Packet Timing<br />
Developer’s <strong>Guide</strong> Page 51<br />
All <strong>INSTEON</strong> powerline packets contain 24 bits. Since a bit takes 10 cycles of 131.65<br />
KHz carrier, there are 240 cycles of carrier in an <strong>INSTEON</strong> packet. An <strong>INSTEON</strong><br />
powerline packet therefore lasts 1.823 milliseconds.<br />
The powerline environment is notorious for uncontrolled noise, especially highamplitude<br />
spikes caused by motors, dimmers and compact fluorescent lighting. This<br />
noise is minimal during the time that the current on the powerline reverses direction,<br />
a time known as the powerline zero crossing. Therefore, <strong>INSTEON</strong> packets are<br />
transmitted during the zero crossing quiet time, as shown in the figure below.<br />
Insteon<br />
800 us<br />
Zero Crossing<br />
Insteon<br />
X10<br />
1823 us<br />
1023 us<br />
1 BIT = 10 Cycles of 131.65 KHz<br />
16.67 ms<br />
Insteon<br />
X10<br />
24 BITS @ 13.165 Kbps<br />
Zero Crossing<br />
X10<br />
1 BURST = ½ BIT = 120 Cycles of 120 KHz<br />
The top of the figure shows a single powerline cycle, which possesses two zero<br />
crossings. An <strong>INSTEON</strong> packet is shown at each zero crossing. <strong>INSTEON</strong> packets<br />
begin 800 microseconds before a zero crossing and last until 1023 microseconds<br />
after the zero crossing.<br />
X10 Compatibility<br />
The figure also shows how X10 signals are applied to the powerline. X10 is the<br />
signaling method used by many devices already deployed on powerlines around the<br />
world. Compatibility 2 with this existing population of legacy X10 devices is an<br />
important feature of <strong>INSTEON</strong>. At a minimum, X10 compatibility means that<br />
<strong>INSTEON</strong> and X10 signals can coexist with each other, but compatibility also allows<br />
October 14, 2005 © 2005 Smarthome Technology
Developer’s <strong>Guide</strong> Page 52<br />
designers to create hybrid devices that can send and receive both <strong>INSTEON</strong> and X10<br />
signals.<br />
The X10 signal uses a burst of approximately 120 cycles of 120 KHz carrier<br />
beginning at the powerline zero crossing and lasting about 1000 microseconds. A<br />
burst followed by no burst signifies an X10 one bit and no burst followed by a burst<br />
signifies an X10 zero bit. An X10 message begins with two bursts in a row followed<br />
by a one bit, followed by nine data bits. The figure shows an X10 burst at each of<br />
the two zero crossings.<br />
The X10 specification also allows for two copies of the zero crossing burst located<br />
one-third and two-thirds of the way through a half-cycle of power. These points<br />
correspond to the zero crossings of the other two phases of three-phase power.<br />
<strong>INSTEON</strong> is insensitive to those additional X10 bursts and does not transmit them<br />
when sending X10.<br />
The middle of the figure shows an expanded view of an <strong>INSTEON</strong> packet with an X10<br />
burst superimposed. The X10 signal begins at the zero crossing, 800 microseconds<br />
after the beginning of the <strong>INSTEON</strong> packet. Both signals end at approximately the<br />
same time, 1023 microseconds after the zero crossing.<br />
<strong>INSTEON</strong> devices achieve compatibility with X10 by listening for an <strong>INSTEON</strong> signal<br />
beginning 800 microseconds before the zero crossing. <strong>INSTEON</strong> receivers<br />
implemented in software can be very sensitive, but at the cost of having to receive a<br />
substantial portion of a packet before being able to validate that a true <strong>INSTEON</strong><br />
packet is being received. Reliable validation may not occur until as much as 450<br />
microseconds after the zero crossing, although an <strong>INSTEON</strong> device will still begin<br />
listening for a possible X10 burst right at the zero crossing. If at the 450microsecond<br />
mark the <strong>INSTEON</strong> receiver validates that it is not receiving an<br />
<strong>INSTEON</strong> packet, but that there is an X10 burst present, the <strong>INSTEON</strong> receiver will<br />
switch to X10 mode and listen for a complete X10 message over the next 11<br />
powerline cycles. If instead the <strong>INSTEON</strong> device detects that it is receiving an<br />
<strong>INSTEON</strong> packet, it will remain in <strong>INSTEON</strong> mode and not listen for X10 until it<br />
receives the rest of the complete <strong>INSTEON</strong> message.<br />
The bottom of the figure shows that the raw bitrate for <strong>INSTEON</strong> is much faster for<br />
<strong>INSTEON</strong> than for X10. An <strong>INSTEON</strong> bit requires ten cycles of 131.65 KHz carrier, or<br />
75.96 microseconds, whereas an X10 bit requires two 120-cycle bursts of 120 KHz.<br />
One X10 burst takes 1000 microseconds, but since each X10 burst is sent at a zero<br />
crossing, it takes 16,667 microseconds to send the two bursts in a bit, resulting in a<br />
sustained bitrate of 60 bits per second. <strong>INSTEON</strong> packets consist of 24 bits, and an<br />
<strong>INSTEON</strong> packet can be sent during each zero crossing, so the nominal raw<br />
sustained bitrate for <strong>INSTEON</strong> is 2880 bits per second, 48 times faster than X10.<br />
Note that this nominal <strong>INSTEON</strong> bitrate must be derated to account for packet and<br />
message overhead, as well as message retransmissions. See <strong>INSTEON</strong> Powerline<br />
Data Rates, below, for details.<br />
Message Timeslots<br />
To allow time for potential retransmission of a message by <strong>INSTEON</strong> RF devices, an<br />
<strong>INSTEON</strong> transmitter waits for one additional zero crossing after sending a Standard<br />
message, or for two zero crossings after sending an Extended message. Therefore,<br />
the total number of zero crossings needed to send a Standard message is 6, or 13<br />
for an Extended message. This number, 6 or 13, constitutes an <strong>INSTEON</strong> message<br />
timeslot.<br />
October 14, 2005 © 2005 Smarthome Technology
Standard Message Timeslots<br />
Developer’s <strong>Guide</strong> Page 53<br />
The figure below shows a series of 5-packet Standard <strong>INSTEON</strong> messages being sent<br />
on the powerline. <strong>INSTEON</strong> transmitters wait for one zero crossing after each<br />
Standard message before sending another message, so the Standard message<br />
timeslot is 6 zero crossings, or 50 milliseconds, in length.<br />
Standard Message<br />
Timeslot 1<br />
Standard Message<br />
Timeslot 2<br />
Extended Message Timeslots<br />
Standard Message<br />
Timeslot 3<br />
Standard Message<br />
Timeslot 4<br />
The next figure shows a series of 11-packet Extended <strong>INSTEON</strong> messages being sent<br />
on the powerline. <strong>INSTEON</strong> transmitters wait for two zero crossings after each<br />
Extended message before sending another message, so the Extended message<br />
timeslot is 13 zero crossings, or 108.33 milliseconds, in length.<br />
Extended Message<br />
Timeslot 1<br />
Extended Message<br />
Timeslot 2<br />
October 14, 2005 © 2005 Smarthome Technology
<strong>INSTEON</strong> Powerline Data Rates<br />
Developer’s <strong>Guide</strong> Page 54<br />
<strong>INSTEON</strong> Standard messages contain 120 raw data bits and require 6 zero crossings,<br />
or 50 milliseconds to send. Extended messages contain 264 raw data bits and<br />
require 13 zero crossings, or 108.33 milliseconds to send. Therefore, the actual raw<br />
bitrate for <strong>INSTEON</strong> is 2400 bits per second for Standard messages, or 2437 bits per<br />
second for Extended messages, instead of the 2880 bits per second it would be<br />
without waiting for the extra zero crossings.<br />
<strong>INSTEON</strong> Standard messages contain 9 bytes (72 bits) of usable data, not counting<br />
packet sync and start code bits, nor the message CRC byte. Extended messages<br />
contain 23 bytes (184 bits) of usable data using the same criteria. Therefore, the<br />
bitrates for usable data are further reduced to 1440 bits per second for Standard<br />
messages and 1698 bits per second for Extended messages. If one only counts the<br />
14 bytes (112 bits) of User Data in Extended messages, the User Data bitrate is<br />
1034 bits per second.<br />
These data rates assume that messages are sent with Max Hops set to zero and that<br />
there are no message retries. They also do not take into account the time it takes<br />
for a message to be acknowledged. The table below shows net data rates when<br />
multiple hops and message acknowledgement are taken into account. To account for<br />
retries, divide the given data rates by one plus the number of retries (up to a<br />
maximum of 5 possible retries).<br />
Max<br />
Hops<br />
Condition Bits per Second<br />
ACK Retries<br />
Standard<br />
Message<br />
Usable<br />
Data<br />
Extended<br />
Message<br />
Usable<br />
Data<br />
Extended<br />
Message<br />
User<br />
Data<br />
Only<br />
0 No 0 1440 1698 1034<br />
1 No 0 720 849 517<br />
2 No 0 480 566 345<br />
3 No 0 360 425 259<br />
0 Yes 0 720 849 517<br />
1 Yes 0 360 425 259<br />
2 Yes 0 240 283 173<br />
3 Yes 0 180 213 130<br />
October 14, 2005 © 2005 Smarthome Technology
RF Signaling<br />
Developer’s <strong>Guide</strong> Page 55<br />
RF <strong>INSTEON</strong> devices can send and receive the same messages that appear on the<br />
powerline. Unlike powerline messages, however, messages sent by RF are not<br />
broken up into smaller packets sent at powerline zero crossings, but instead are sent<br />
whole, as was shown in the section RF Packets. As with powerline, there are two RF<br />
message lengths: Standard 10-byte messages and Extended 24-byte messages.<br />
The table below gives the specifications for <strong>INSTEON</strong> RF signaling.<br />
RF Specification Value<br />
Center Frequency 904 MHz<br />
Data Encoding Method Manchester<br />
Modulation Method FSK<br />
FSK Deviation 64 KHz<br />
FSK Symbol Rate 76,800 symbols per second<br />
Data Rate 38,400 bits per second<br />
Range 150 feet outdoors<br />
The center frequency lies in the band 902 to 924 MHz, which is permitted for<br />
unlicensed operation in the United States. Each bit is Manchester encoded, meaning<br />
that two symbols are sent for each bit. A one-symbol followed by a zero-symbol<br />
designates a one-bit, and a zero-symbol followed by a one-symbol designates a<br />
zero-bit. Symbols are modulated onto the carrier using frequency-shift keying<br />
(FSK), where a zero-symbol modulates the carrier half the FSK deviation frequency<br />
downward and a one-symbol modulates the carrier half the FSK deviation frequency<br />
upward. The FSK deviation frequency chosen for <strong>INSTEON</strong> is 64 KHz. Symbols are<br />
modulated onto the carrier at 76,800 symbols per second, resulting in a raw data<br />
rata of half that, or 38,400 bits per second. The typical range for free-space<br />
reception is 150 feet, which is reduced in the presence of walls and other RF energy<br />
absorbers.<br />
October 14, 2005 © 2005 Smarthome Technology
Developer’s <strong>Guide</strong> Page 56<br />
<strong>INSTEON</strong> devices transmit data with the most-significant bit sent first. Referring to<br />
the figures below, RF messages begin with two sync bytes consisting of AAAA in<br />
hexadecimal, followed by a start code byte of C3 in hexadecimal. Ten data bytes<br />
follow in Standard messages, or twenty-four data bytes in Extended messages. The<br />
last data byte in a message is a CRC 3 over the data bytes as explained above (see<br />
Message Integrity Byte).<br />
RF Standard Message – 1 Packet<br />
AA AA C3 x x x x x x x x x x n<br />
2<br />
Sync<br />
bytes<br />
1<br />
Start<br />
Code<br />
byte<br />
80 Data Bits (10 Data bytes) CRC 3<br />
RF Extended Message – 1 Packet<br />
112 total bits = 14 bytes<br />
80 Data bits = 10 bytes<br />
224 total bits = 28 bytes<br />
192 Data bits = 24 bytes<br />
AA AA C3 x x x x x x x X x x x x x x x x x x x x x x x x n<br />
2<br />
Sync<br />
bytes<br />
1<br />
Start<br />
Code<br />
byte<br />
192 Data Bits (24 Data bytes) CRC 3<br />
It takes 2.708 milliseconds to send a 104-bit Standard message, and 5.625<br />
milliseconds to send a 216-bit Extended message. Zero crossings on the powerline<br />
occur every 8.333 milliseconds, so a Standard or Extended RF message can be sent<br />
during one powerline half-cycle. The waiting times after sending powerline<br />
messages, as shown in the section Powerline Packets, are to allow sufficient time for<br />
<strong>INSTEON</strong> RF devices, if present, to retransmit a powerline message.<br />
October 14, 2005 © 2005 Smarthome Technology
Simulcasting<br />
Developer’s <strong>Guide</strong> Page 57<br />
By following the above rules for message propagation, <strong>INSTEON</strong> systems achieve a<br />
marked increase in the reliability of communications. The reason is that multiple<br />
<strong>INSTEON</strong> devices can transmit the same message at the same time within a given<br />
timeslot. <strong>INSTEON</strong> devices within range of each other thus “help each other out.”<br />
Most networking protocols for shared physical media prohibit multiple devices from<br />
simultaneously transmitting within the same band by adopting complex routing<br />
algorithms. In contrast, <strong>INSTEON</strong> turns what is usually a problem into a benefit by<br />
ensuring that devices transmitting simultaneously will be sending the same<br />
messages in synchrony with each other.<br />
Powerline Simulcasting<br />
One might think that multiple <strong>INSTEON</strong> devices transmitting on the powerline could<br />
easily cancel each other out rather than boost each other. In practice, even if one<br />
were trying to nullify one signal with another, signal cancellation by multiple devices<br />
would be extremely difficult to arrange. The reason is that for two signals to cancel<br />
at a given receiver, the two transmitters would have to send carriers such that the<br />
receiver would see them as exactly equal in amplitude and very nearly 180 degrees<br />
out of phase. The probability of this situation occurring and persisting for extended<br />
periods is low.<br />
The crystals used on typical <strong>INSTEON</strong> devices to generate the powerline carrier<br />
frequency of 131.65 KHz run independently of each other with a frequency tolerance<br />
of a few tenths of a percent. Phase relationships among multiple powerline carriers<br />
therefore will drift, although slowly with respect to the 1823 microsecond duration of<br />
an <strong>INSTEON</strong> packet. Even if the phases of two transmitters happened to cancel, it is<br />
very unlikely that the amplitudes would also be equal at the location of a receiver, so<br />
a receiver would very likely still see some signal even in the worst-case transient<br />
phase relationship. <strong>INSTEON</strong> receivers have a wide dynamic range, from millivolts<br />
to five volts or so, which will allow them to track signals even if they fade<br />
temporarily. Adding more transmitters reduces the probability of signal cancellation<br />
even more. Rather, the probability that the sum of all the signals will increase in<br />
signal strength becomes much greater with source diversity.<br />
The <strong>INSTEON</strong> powerline carrier is modulated using binary phase-shift keying (BPSK),<br />
meaning that receivers are looking for 180-degree phase shifts in the carrier to<br />
detect changes in a string of bits from a one to a zero or vice-versa. Multiple<br />
transmitters, regardless of the absolute phase of their carriers, will produce signals<br />
whose sum still possesses 180-degree phase reversals at bit-change boundaries, so<br />
long as their relative carrier frequencies do not shift more than a few degrees over a<br />
packet time. Of course, bit timings for each transmitter need to be fairly well locked,<br />
so <strong>INSTEON</strong> transmitters are synchronized to powerline zero crossings. An <strong>INSTEON</strong><br />
bit lasts for ten cycles of the 131.65 KHz powerline carrier, or 76 microseconds. The<br />
powerline zero crossing detector should be accurate within one or two carrier periods<br />
so that bits received from multiple transmitters will overlay each other.<br />
In practice, multiple <strong>INSTEON</strong> powerline transmitters simulcasting the same<br />
message will improve the strength of the powerline signal throughout a building.<br />
October 14, 2005 © 2005 Smarthome Technology
RF Simulcasting<br />
Developer’s <strong>Guide</strong> Page 58<br />
Since RF signaling is used as an extension to powerline signaling, it also is based on<br />
simulcasting. However, because of the short wavelength of 900 MHz RF carrier<br />
signals, standing wave interference patterns can form where the RF carrier signal is<br />
reduced, even when the carrier and data are ideally synchronized.<br />
As with powerline, for a cancellation to occur, two carriers must be 180 degrees out<br />
of phase and the amplitudes must be the same. Perfect cancellation is practically<br />
impossible to obtain. In general, two co-located carriers on the same frequency with<br />
random phase relationships and the same antenna polarization will sum to a power<br />
level greater than that of just one transmitter 67% of the time. As one of the<br />
transmitters is moved away from a receiver, the probability of cancellation drops<br />
further because the signal amplitudes will be unequal. As the number of<br />
transmitters increases, the probability of cancellation becomes nearly zero.<br />
Mobile <strong>INSTEON</strong> RF devices, such as handheld controllers, are battery operated. To<br />
conserve power, mobile devices are not configured as RF Repeaters, but only as<br />
message originators, so RF simulcasting is not an issue for them. <strong>INSTEON</strong> devices<br />
that do repeat RF messages are attached to the powerline, so most of them will not<br />
be moved around after initial setup. During setup, such RF devices can be located,<br />
and their antennas adjusted, so that no signal cancellation occurs. With the location<br />
of the transmitters fixed, the non-canceling configuration will be maintained<br />
indefinitely.<br />
RF/Powerline Synchronization<br />
<strong>INSTEON</strong> RF devices attached to the powerline use the zero crossing for message<br />
synchronization. These devices receive <strong>INSTEON</strong> messages synchronously on the<br />
powerline, synchronously via RF from RF Repeaters, or possibly asynchronously via<br />
RF from mobile RF devices.<br />
Messages that need to be retransmitted will have a Hops Left count greater than<br />
zero. If the <strong>INSTEON</strong> device receives such a message from the powerline, it will first<br />
retransmit the message using RF as soon as it has received the last packet of the<br />
powerline message, then it will retransmit the message on the powerline in the next<br />
timeslot. If the device receives the message via RF, it will first retransmit the<br />
message on the powerline in the next timeslot, then it will retransmit the message<br />
using RF immediately after sending the last packet of the powerline message. In this<br />
way, RF message received asynchronously will be resynchronized to the powerline<br />
zero crossing at the earliest opportunity.<br />
October 14, 2005 © 2005 Smarthome Technology
<strong>INSTEON</strong> Network Usage<br />
Developer’s <strong>Guide</strong> Page 59<br />
<strong>INSTEON</strong> messaging technology can be used in many different ways in many kinds of<br />
devices. To properly utilize the full set of possible <strong>INSTEON</strong> message types, devices<br />
must share a common set of specific, preassigned number values for the one- and<br />
two-byte Commands, two-byte Device Types, one-byte Device Attributes, one- or<br />
two-byte ACK statuses, and one- or two-byte NAK reasons. Smarthome maintains<br />
the database of allowable values for these parameters.<br />
Because <strong>INSTEON</strong> devices are individually preassigned a three-byte Address at the<br />
time of manufacture, complex procedures for assigning network addresses in the<br />
field are not needed. Instead, <strong>INSTEON</strong> devices are logically linked together in the<br />
field using a simple, uniform procedure.<br />
<strong>INSTEON</strong> Extended messages allow programmers to devise all kinds of meanings for<br />
the User Data that can be exchanged among devices. For example, many <strong>INSTEON</strong><br />
devices include an interpreter for an application language, called SALad, which is<br />
compiled into token strings and downloaded into devices using Extended messages.<br />
Also, secure messaging can be implemented by sending encrypted payloads in<br />
Extended messages.<br />
In this section<br />
<strong>INSTEON</strong> Commands<br />
Explains the role of Commands in <strong>INSTEON</strong> messages and enumerates all<br />
currently defined Commands.<br />
<strong>INSTEON</strong> Device Classes<br />
Explains how devices identify themselves to other devices in an <strong>INSTEON</strong><br />
network.<br />
<strong>INSTEON</strong> Device Linking<br />
Explains how <strong>INSTEON</strong> devices are logically linked together in Groups and gives<br />
examples.<br />
<strong>INSTEON</strong> Extended Messages<br />
Discusses how <strong>INSTEON</strong> Extended messages can transport arbitrary User Data.<br />
<strong>INSTEON</strong> Security<br />
Gives an overview of how <strong>INSTEON</strong> handles network security issues.<br />
October 14, 2005 © 2005 Smarthome Technology
<strong>INSTEON</strong> Commands<br />
Developer’s <strong>Guide</strong> Page 60<br />
<strong>INSTEON</strong>’s simplicity stems from the fact that Standard messages are all 10 bytes in<br />
length, and they contain just two payload bytes, Command 1 and Command 2.<br />
Smarthome maintains the table of possible <strong>INSTEON</strong> Commands. This table is<br />
currently very sparsely populated. Designers who wish to create <strong>INSTEON</strong> devices<br />
that implement new Commands should contact Smarthome at info@insteon.net. The<br />
current <strong>INSTEON</strong> Commands are enumerated in the <strong>INSTEON</strong> Command Tables.<br />
The basic rules for handling <strong>INSTEON</strong> Commands depend on whether a device is<br />
currently acting as a Controller or a Responder.<br />
Controllers have a repertoire of Commands that they can send, usually set by the<br />
firmware in the device. Examples for a lighting controller might include On, Off,<br />
Bright, Dim, Fast On, and Fast Off. Obviously, a Controller can only send the<br />
Commands it knows about, and no others.<br />
Responders likewise have a repertoire of Commands that they can act upon. For<br />
example, a lamp dimmer’s firmware might contain procedures to respond to On, Off,<br />
Bright, and Dim Commands, but not Fast On and Fast Off. A Responder will only act<br />
on the Commands it knows about, and no others.<br />
Smarthome maintains a cross-reference between Device Classes and Commands that<br />
a device must implement for <strong>INSTEON</strong> conformance certification. Contact<br />
Smarthome at info@insteon.net for more information.<br />
In this section<br />
<strong>INSTEON</strong> Command 1 and 2<br />
Explains the usage of the Command 1 and Command 2 fields in <strong>INSTEON</strong><br />
messages.<br />
<strong>INSTEON</strong> Command Tables<br />
Enumerates all of the <strong>INSTEON</strong> Commands and gives details on how to use them.<br />
<strong>INSTEON</strong> Command Examples<br />
Gives some examples of using <strong>INSTEON</strong> Commands to alter <strong>INSTEON</strong> device<br />
behavior.<br />
October 14, 2005 © 2005 Smarthome Technology
<strong>INSTEON</strong> Command 1 and 2<br />
<strong>INSTEON</strong> Command 1<br />
Developer’s <strong>Guide</strong> Page 61<br />
Command 1 holds an 8-bit number representing the <strong>INSTEON</strong> Primary Command to<br />
execute.<br />
<strong>INSTEON</strong> Command 2<br />
The interpretation of the Command 2 field depends on the Primary Command in the<br />
Command 1 field.<br />
Parameter<br />
The Command 2 field can be a parameter for the Primary Command. For example,<br />
Command 0x11 (On) has a parameter in Command 2 ranging from 0x00 to 0xFF<br />
representing the On-Level.<br />
Subcommand<br />
Command 2 can act as a Subcommand for certain blocks of Primary Commands.<br />
Taken together, the 2-byte Primary-plus-Subcommands allow for expansion of the<br />
command space.<br />
Group Number<br />
For Groups of linked devices, Controllers first send a Group Broadcast message<br />
containing a Primary Command to all devices in the Group at once. Responders in<br />
the Group will execute the Primary Command right away, but they will not reply with<br />
an acknowledgement. To ensure reliability, a Controller follows up a Group<br />
Broadcast with a Group Cleanup message sent individually to each member of the<br />
Group. In Group Cleanup messages Command 2 contains the Group Number.<br />
Acknowledgement<br />
Command 2 can return data to the sending device in an acknowledgement message.<br />
For example, an ACK message responding to Commands On, Off, Bright, Dim, Fast<br />
On, Fast Off, Start Manual Change, and Stop Manual Change will hold the On-Level<br />
in the Command 2 field. If one of these Commands is sent and the response is a<br />
NAK message, then the Command 2 field will hold the NAK reason code.<br />
October 14, 2005 © 2005 Smarthome Technology
<strong>INSTEON</strong> Command Tables<br />
There are two classes of <strong>INSTEON</strong> Commands:<br />
Developer’s <strong>Guide</strong> Page 62<br />
<strong>INSTEON</strong> Common Commands<br />
Used in Direct (Point-to-Point), Group Broadcast, and Group Cleanup messages.<br />
<strong>INSTEON</strong> Broadcast Commands<br />
Used in Broadcast (but not Group Broadcast) messages.<br />
The Command Numbers are reused in each class. For example, a Command Number<br />
0x01 in a Broadcast message denotes SET Button Pressed Slave, but a Command<br />
Number 0x01 in a Direct message denotes Assign to Group. See <strong>INSTEON</strong> Message<br />
Summary Table for more information on <strong>INSTEON</strong> message types.<br />
In This Section<br />
<strong>INSTEON</strong> Common Commands<br />
Describes the <strong>INSTEON</strong> Commands used in Direct, Group Broadcast, and Group<br />
Cleanup messages.<br />
<strong>INSTEON</strong> Broadcast Commands<br />
Describes the <strong>INSTEON</strong> Commands used in Broadcast (but not Group Broadcast)<br />
messages.<br />
October 14, 2005 © 2005 Smarthome Technology
<strong>INSTEON</strong> Common Commands<br />
Developer’s <strong>Guide</strong> Page 63<br />
These <strong>INSTEON</strong> Commands can be used in Direct, Group Broadcast, and Group<br />
Cleanup <strong>INSTEON</strong> messages. (Use <strong>INSTEON</strong> Broadcast Commands in Broadcast<br />
messages.) Recipients of Direct and Group Cleanup messages will respond to the<br />
message originator with an Acknowledge message, but recipients of Group Broadcast<br />
messages will not (see <strong>INSTEON</strong> Message Summary Table).<br />
<strong>INSTEON</strong> Common Command Summary Table<br />
This table lists all current <strong>INSTEON</strong> Common Commands.<br />
Command Name<br />
Gives the descriptive name of the <strong>INSTEON</strong> Command. Commands marked *<br />
have not been implemented and are reserved for possible future use.<br />
Command 1<br />
Gives the Command Number used in the Command 1 field of the <strong>INSTEON</strong><br />
message to identify this <strong>INSTEON</strong> Command.<br />
Command 2<br />
Describes the contents of the Command 2 field of the <strong>INSTEON</strong> message. In<br />
Group Cleanup messages, the Command 2 field contains the Group Number. Set<br />
this field to 0x00 if not otherwise specified.<br />
Note<br />
See the item with the same note number in <strong>INSTEON</strong> Common Command Details<br />
for more information.<br />
Description<br />
Briefly describes what the command does.<br />
Command Name Command 1 Command 2 Note Description<br />
*Reserved 0x00 1<br />
Assign to Group 0x01 Group Number 2 Used during <strong>INSTEON</strong> Device Linking<br />
session.<br />
Delete from Group 0x02 Group Number 2 Used during unlinking session.<br />
*Read Connections 0x03 Group Number<br />
0=All<br />
1<br />
Send as Extended message.<br />
Returned Extended ACK message will<br />
contain the connections.<br />
*Read Device Data 0x04 1 Device Type and other information<br />
specific to <strong>INSTEON</strong> device returned<br />
in Extended Message.<br />
*Factory Reset 0x05 Security Code 1 Reset to Factory default conditions.<br />
*Device Reset 0x06 Security Code 1 Reset to Factory default conditions<br />
but keep connections and links.<br />
*Terminate<br />
Download<br />
0x07 1 Stops download.<br />
*Reserved 0x08 1<br />
*Enter Master<br />
Program Mode<br />
0x09 Group Number 1<br />
October 14, 2005 © 2005 Smarthome Technology
Developer’s <strong>Guide</strong> Page 64<br />
Command Name Command 1 Command 2 Note Description<br />
*Enter Slave<br />
Program Mode<br />
*Reserved 0x0B ⇒<br />
0x0F<br />
0x0A 1<br />
Ping 0x10 Receiving device first returns an ACK<br />
message, then it sends a Device<br />
Identification Broadcast.<br />
ON 0x11 On Level (0x00 ⇒<br />
0xFF), or Group<br />
number<br />
*Fast ON 0x12 On Level (0x00 ⇒<br />
0xFF), or Group<br />
number<br />
OFF 0x13 None, or Group<br />
number<br />
*Fast OFF 0x14 None, or Group<br />
number<br />
Bright 0x15 None, or Group<br />
number<br />
Dim 0x16 None, or Group<br />
number<br />
Start Manual<br />
Change<br />
Stop Manual<br />
Change<br />
1<br />
1<br />
1<br />
Brighten one step. There are 32<br />
steps from off to full brightness.<br />
Returned ACK message will contain<br />
the On-Level in Command 2.<br />
Dim one step. There are 32 steps<br />
from off to full brightness.<br />
Returned ACK message will contain<br />
the On-Level in Command 2.<br />
0x17 1 = Up, 0 = Down Begin changing On-Level.<br />
0x18 None Stop changing On-Level.<br />
Status Request 0x19 None Returned ACK message will contain<br />
the status (often the On-Level) in<br />
Command 2. Command 1 will<br />
contain a Link Database Delta<br />
number that increments every time<br />
there is a change in the addressee’s<br />
<strong>INSTEON</strong> Link Database.<br />
*Status Report 0x1A New Status 1 Sent to controller when local state<br />
changes.<br />
*Read Last Level 0x1B None 1 Returned ACK message will contain<br />
the requested data in Command 2.<br />
*Set Last Level 0x1C On-Level 1<br />
*Read Preset Level 0x1D None 1 Returned ACK message will contain<br />
the requested data in Command 2.<br />
*Set Preset Level 0x1E On-Level 1<br />
October 14, 2005 © 2005 Smarthome Technology
Developer’s <strong>Guide</strong> Page 65<br />
Command Name Command 1 Command 2 Note Description<br />
*Read Operating<br />
Flags<br />
*Set Operating<br />
Flags<br />
*Delete Group X10<br />
Address<br />
0x1F None 1 Returned ACK message will contain<br />
the requested data in Command 2.<br />
0x20 Flags 1<br />
0x21 Group Number 1 Sent to a device to delete the<br />
assigned X10 address for a group<br />
within the device.<br />
*Load Off 0x22 1 Indicates manual load status change.<br />
*Load On 0x23 1 Indicates manual load status change.<br />
Do Read EE 0x24 None Read initialization values from<br />
EEPROM, so that they will take effect<br />
after being poked.<br />
*Level Poke 0x25 On-Level 1 Set new On-Level.<br />
*Rate Poke 0x26 Ramp Rate 1 Set new Ramp Rate.<br />
*Current Status 0x27 Usually an On-<br />
Level<br />
Set Address MSB 0x28 High byte of 16-bit<br />
address<br />
3<br />
Can be used to update a companion<br />
device.<br />
Set Most-significant Byte of EEPROM<br />
address for peek or poke.<br />
Poke 0x29 Byte to write 3 Poke Data byte into address<br />
previously loaded with Set Address<br />
MSB and Peek commands (Peek sets<br />
LSB).<br />
Poke Extended 0x2A LSB of address to<br />
begin writing up to<br />
13 bytes to<br />
Peek 0x2B LSB of address to<br />
peek or poke<br />
Peek Internal 0x2C LSB of internal<br />
memory address to<br />
read from<br />
3<br />
3<br />
3<br />
Poke up to 13 bytes starting at the<br />
address whose high byte was<br />
previously set using Set Address<br />
MSB.<br />
This command must be sent within<br />
an Extended message. Put the<br />
number of bytes to poke in the first<br />
byte of User Data, and the actual<br />
bytes to poke in the remaining 13<br />
bytes.<br />
Peek can be sent within a Standard<br />
or an Extended message. If<br />
Extended, put the number of bytes<br />
to peek in the first byte of User Data.<br />
The returned ACK message will<br />
contain the first peeked byte in<br />
Command 2. The Extended ACK<br />
message to an Extended Peek will<br />
return up to 14 remaining bytes in<br />
User Data.<br />
Peek is also used to set the LSB for<br />
one-byte pokes.<br />
Works like Peek, except only used to<br />
read from internal memory of a<br />
Smarthome ControLinc V2.<br />
October 14, 2005 © 2005 Smarthome Technology
Developer’s <strong>Guide</strong> Page 66<br />
Command Name Command 1 Command 2 Note Description<br />
Poke Internal 0x2D Byte to write 3 Works like Poke, except only used to<br />
write one byte into internal EEPROM<br />
of a Smarthome ControLinc V2.<br />
*Reserved 0x2E ⇒<br />
0x80<br />
*Assign to<br />
Companion Group<br />
*Reserved 0x82 ⇒<br />
0xEF<br />
*Reserved for RF<br />
Devices<br />
1<br />
0x81 1 Allows Slaves of a Master to follow<br />
the Master when the Master is<br />
controlled by a companion device.<br />
0xF0 ⇒<br />
0xFB<br />
Send RF Test Signal 0xFC Causes RF devices to send a 4second<br />
test message for other RF<br />
units to hear.<br />
Request RF Test<br />
Report<br />
Reset RF Test<br />
Report<br />
1<br />
1<br />
0xFD Causes an RF receiver to transmit<br />
back the results of the last RF test.<br />
0xFE Clears an RF receiver’s memory of<br />
the results of the previous RF Test.<br />
RF Air Only Test 0xFF Send <strong>INSTEON</strong> message via RF only<br />
(not powerline).<br />
<strong>INSTEON</strong> Common Command Details<br />
The numbers below refer to the Note column in the above <strong>INSTEON</strong> Common<br />
Command Summary Table.<br />
1. Not Implemented<br />
These Commands are reserved for possible future use.<br />
2. Assign to Group (0x01), Delete from Group (0x02)<br />
These Commands are used for <strong>INSTEON</strong> Device Linking. See Example of an<br />
<strong>INSTEON</strong> Linking Session. For sample <strong>INSTEON</strong> messages that use the Assign to<br />
Group (0x01) command.<br />
3. Peek and Poke (0x29 ⇒ 0x2D)<br />
You can use the Peek and Poke <strong>INSTEON</strong> Commands (0x28 ⇒ 0x2D) to<br />
remotely read or write memory in <strong>INSTEON</strong> devices. For example, you could<br />
inspect or alter the <strong>INSTEON</strong> Link Database of an <strong>INSTEON</strong> device to determine<br />
which <strong>INSTEON</strong> Groups it belongs to (i.e. which other <strong>INSTEON</strong> devices it has<br />
links to).<br />
SALad-enabled <strong>INSTEON</strong> devices, such as The Smarthome PowerLinc Controller,<br />
map all memory to one Flat Memory Map, but other <strong>INSTEON</strong> devices, such as<br />
Smarthome’s ControLinc V2, LampLinc V2, and SwitchLinc V2, do not have a<br />
flat address space. For flat devices, use the Peek (0x2B), Poke (0x29), and<br />
October 14, 2005 © 2005 Smarthome Technology
Developer’s <strong>Guide</strong> Page 67<br />
Poke Extended (0x2A) to access all memory. For non-flat devices use the<br />
Peek (0x2B), Poke (0x29), and Poke Extended (0x2A) to access external<br />
EEPROM. You only can use Peek Internal (0x2C), and Poke Internal (0x2D)<br />
to access internal EEPROM of the ControLinc V2. Note that you cannot access a<br />
device’s ROM using these commands.<br />
To peek or poke remote memory data, first use the Set Address MSB (0x28)<br />
command to set the high byte of the 16-bit address you want to read from or<br />
write to. You will set the LSB of the address differently depending on what you<br />
will be doing next. If you are going to Poke (0x29) or Poke Internal (0x2D)<br />
one byte of data, you first have to execute a Peek (0x2B) command to set the<br />
address LSB. In the other cases, Peek (0x2B), Peek Internal (0x2C), and<br />
Poke Extended (0x2A), you will set the LSB in the command itself. Note that<br />
the address LSB does not auto-increment.<br />
To peek one byte of data, use Peek (0x2B) or Peek Internal (0x2C) in a<br />
message of Standard length. The Standard length Acknowledge message that<br />
you receive back will contain the peeked byte in the Command 2 field.<br />
To peek more than one byte of data in a single message, use Peek (0x2B) or<br />
Peek Internal (0x2C) in a message of Extended length. Put the number of<br />
bytes you wish to read, 1 through 15 (0x00 ⇒ 0x0F) in the first byte of the User<br />
Data field. It does not matter what you put in the remaining 13 bytes of the User<br />
Data field. The Extended length Acknowledge message that you receive back will<br />
contain the first peeked byte in the Command 2 field, and the remaining peeked<br />
bytes (up to 14 of them) in the User Data field.<br />
To poke one byte of data, use Poke (0x29) or Poke Internal (0x2D) in a<br />
message of Standard length. Remember to set the address you want to poke to<br />
by using a Set Address MSB (0x28) command followed by a Peek (0x2B)<br />
command. The Command 2 field of the Standard length Acknowledge message<br />
that you receive back will contain the value of the byte you are poking before it<br />
was altered by the poke.<br />
To poke more than one byte of data in a single message, use Poke Extended<br />
(0x2A) in a message of Extended length. Put the LSB of the starting address<br />
you will poke the bytes to in the Command 1 field. Put the number of bytes you<br />
wish to poke, 1 through 13 (0x00 ⇒ 0x0D) in the first byte of the User Data field,<br />
and the bytes you wish to poke the remaining 13 bytes of the User Data field. If<br />
you are poking fewer than 13 bytes, it does not matter what the unused bytes of<br />
the User Data field contain. The Extended length Acknowledge message that you<br />
receive back will contain the value of the poked bytes before you altered them.<br />
The first byte will be in the Command 2 field, and the remaining bytes (up to 13<br />
of them) will be in the User Data field.<br />
October 14, 2005 © 2005 Smarthome Technology
NAK Reason Codes<br />
Developer’s <strong>Guide</strong> Page 68<br />
If the recipient of a Direct or Group Cleanup message responds to the message<br />
originator with a NAK, the Acknowledge message will contain the reason for the NAK<br />
in the Command 2 field (see <strong>INSTEON</strong> Message Summary Table). These are the NAK<br />
Reason codes:<br />
Code NAK Reason<br />
0x00 ⇒<br />
0xFD<br />
Reserved<br />
0xFE No Load<br />
0xFF Not in Group<br />
October 14, 2005 © 2005 Smarthome Technology
<strong>INSTEON</strong> Broadcast Commands<br />
Developer’s <strong>Guide</strong> Page 69<br />
These <strong>INSTEON</strong> Commands can only be used in <strong>INSTEON</strong> Broadcast Messages. (Use<br />
<strong>INSTEON</strong> Common Commands in Direct, Group Broadcast, and Group Cleanup<br />
messages.)<br />
<strong>INSTEON</strong> Broadcast messages contain information for all recipients. In Broadcast<br />
messages the To Address field of the message contains the 16-bit Device Type and<br />
8-bit Firmware Revision (see <strong>INSTEON</strong> Message Summary Table).<br />
Recipients of Broadcast messages will not respond with an Acknowledge message,<br />
but they may engage in a followup conversation if applicable. For an example of how<br />
this works, see Example of an <strong>INSTEON</strong> Linking Session.<br />
<strong>INSTEON</strong> Broadcast Command Summary Table<br />
This table lists all currently <strong>INSTEON</strong> Broadcast Commands.<br />
Command Name<br />
Gives the descriptive name of the <strong>INSTEON</strong> Broadcast Command. Commands<br />
marked * have not been implemented and are reserved for possible future use.<br />
Command 1<br />
Gives the Command Number used in the Command 1 field of the <strong>INSTEON</strong><br />
Broadcast message to identify this <strong>INSTEON</strong> Command.<br />
Command 2<br />
Describes the contents of the Command 2 field of the <strong>INSTEON</strong> message. This<br />
field is not used by <strong>INSTEON</strong> Broadcast Commands. Set this field to 0x00.<br />
Note<br />
See the item with the same note number in <strong>INSTEON</strong> Broadcast Command<br />
Details for more information.<br />
Description<br />
Briefly describes what the command does.<br />
Command Name Command 1 Command 2 Note Description<br />
*Announce 0x00 None 1<br />
SET Button Pressed<br />
Slave<br />
0x01 None 2 Possible Program Mode for a Slave device<br />
*Status Changed 0x02 None 1<br />
SET Button Pressed<br />
Master<br />
*Reserved 0x04 ⇒<br />
0x48<br />
0x03 None 2 Possible Program Mode for a Master device<br />
Debug Report 0x49 None 3 The high and low bytes of the Program<br />
Counter (for a SALad program being<br />
remotely debugged) are returned in the<br />
two low bytes of the To Address. See<br />
IBIOS Remote Debugging.<br />
*Reserved 0x4A ⇒<br />
0xFF<br />
October 14, 2005 © 2005 Smarthome Technology<br />
1<br />
1
<strong>INSTEON</strong> Broadcast Command Details<br />
Developer’s <strong>Guide</strong> Page 70<br />
The numbers below refer to the Note column in the above <strong>INSTEON</strong> Broadcast<br />
Command Summary Table.<br />
1. Not Implemented<br />
These Commands are reserved for possible future use.<br />
2. SET Button Pressed Slave (0x01), SET Button Pressed Master (0x03)<br />
These Commands are used for device linking. For an example of how this works,<br />
see Example of an <strong>INSTEON</strong> Linking Session.<br />
3. Debug Report (0x49)<br />
This command returns the 16-bit address contained in the Program Counter of a<br />
SALad program being remotely debugged. The high and low bytes are returned<br />
in the two low bytes of the To Address. See IBIOS Remote Debugging for details.<br />
October 14, 2005 © 2005 Smarthome Technology
<strong>INSTEON</strong> Command Examples<br />
Developer’s <strong>Guide</strong> Page 71<br />
To see some typical examples of <strong>INSTEON</strong> Commands being used in <strong>INSTEON</strong><br />
messages, look in the sections Example of an <strong>INSTEON</strong> Linking Session and Example<br />
of <strong>INSTEON</strong> Group Conversation.<br />
The examples in this section are fairly sophisticated. To use them, you must know<br />
what you are doing. In particular, you should fully understand the <strong>INSTEON</strong> Link<br />
Database, which is not documented until later in this Developer’s <strong>Guide</strong>.<br />
Some of the examples involve directly poking data into an <strong>INSTEON</strong> Device’s Link<br />
Database. If you do this improperly you can corrupt the database and cause the<br />
device to malfunction, in which case you will need to perform a ‘Factory Reset’ on<br />
the <strong>INSTEON</strong> device. The User <strong>Guide</strong> for the device will explain how to do this.<br />
Common Smarthome <strong>INSTEON</strong> Device Memory Locations<br />
This table gives some memory locations found in many Smarthome <strong>INSTEON</strong><br />
devices, such as the LampLinc, SwitchLinc, and KeypadLinc.<br />
Address Variable Name Description<br />
0x0301 EESize MSB of size of EEPROM chip in device<br />
0x0302 EEVersion Firmware Revision number<br />
0x0320 EEOnLevel Preset On-Level for lighting control<br />
0x0321 EERampRate Ramp Rate for lighting control<br />
0x0330 EEX10BaseHouse Base X10 House Code for device<br />
0x0331 EEX10BaseUnit Base X10 Unit Code for device<br />
Assumptions for the Following Examples<br />
The numbers in these examples are all hexadecimal.<br />
We assume that you are using The Smarthome PowerLinc Controller (PLC) with an<br />
<strong>INSTEON</strong> Address of 01.02.03 to send and receive <strong>INSTEON</strong> messages.<br />
The <strong>INSTEON</strong> device you are talking to is a Smarthome LampLinc V2 Dimmer with an<br />
<strong>INSTEON</strong> Address of A1.A2.A3.<br />
All <strong>INSTEON</strong> messages have a Max Hops of 3 and a Hops Left of 3, so the low nibble<br />
of the Flags byte is always 0xF.<br />
These examples involve peeking and poking data directly in the LampLinc’s memory<br />
using the various <strong>INSTEON</strong> peek and poke commands. We assume that you have<br />
read <strong>INSTEON</strong> Common Command Details, Note 3, which explains how to use these<br />
commands.<br />
October 14, 2005 © 2005 Smarthome Technology
Poke a New Ramp Rate<br />
Developer’s <strong>Guide</strong> Page 72<br />
PLC Sends LampLinc Responds<br />
Set Address MSB to 03 OK<br />
From Address 01 02 03 (PLC) A1 A2 A3 (LampLinc)<br />
To Address A1 A2 A3 (LampLinc) 01 02 03 (PLC)<br />
Flags 0F (Direct Message) 2F (Direct ACK Message)<br />
Command 1 28 (Set Address MSB) 28 (Set Address MSB)<br />
Command 2 03 (MSB of 0x0321) 03 (MSB of 0x0321)<br />
Peek to Set Address LSB to 21 OK<br />
From Address 01 02 03 (PLC) A1 A2 A3 (LampLinc)<br />
To Address A1 A2 A3 (LampLinc) 01 02 03 (PLC)<br />
Flags 0F (Direct Message) 2F (Direct ACK Message)<br />
Command 1 2B (Peek) 2B (Peek)<br />
Command 2 21 (LSB of 0x0321) XX (Byte at 0x0321)<br />
Poke 80 at Address 0321 OK<br />
From Address 01 02 03 (PLC) A1 A2 A3 (LampLinc)<br />
To Address A1 A2 A3 (LampLinc) 01 02 03 (PLC)<br />
Flags 0F (Direct Message) 2F (Direct ACK Message)<br />
Command 1 29 (Poke) 29 (Poke)<br />
Command 2 80 (Byte to poke) 80 (Byte to poke)<br />
October 14, 2005 © 2005 Smarthome Technology
Peek Link Database Record at 0x0FF8<br />
Developer’s <strong>Guide</strong> Page 73<br />
Here we assume that the LampLinc’s Non-PLC Link Database has one record at<br />
address 0FF8. The <strong>INSTEON</strong> Address is AABBCC, and the entire 8-byte record is A2<br />
01 AABBCC FF 1C 00.<br />
PLC Sends LampLinc Responds<br />
Set Address MSB to 0F OK<br />
From Address 01 02 03 (PLC) A1 A2 A3 (LampLinc)<br />
To Address A1 A2 A3 (LampLinc) 01 02 03 (PLC)<br />
Flags 0F (Direct Message) 2F (Direct ACK Message)<br />
Command 1 28 (Set Address MSB) 28 (Set Address MSB)<br />
Command 2 0F (MSB of 0x0FF8) 0F (MSB of 0x0FF8)<br />
Peek Extended at Address LSB of F8 OK<br />
From Address 01 02 03 (PLC) A1 A2 A3 (LampLinc)<br />
To Address A1 A2 A3 (LampLinc) 01 02 03 (PLC)<br />
Flags 1F (Direct Extended Message) 3F (Direct ACK Extended Message)<br />
Command 1 2B (Peek) 2B (Peek)<br />
Command 2 F8 (LSB of 0x0FF8) A2 (1st Byte at 0x0FF8)<br />
User Data 00 00 00 00 00 00 00 00 00 00 00 00 00 00 01 AA BB CC FF 1C 00 00 00 00 00 00 00 00<br />
October 14, 2005 © 2005 Smarthome Technology
Poke Link Database Record at 0x0FF8<br />
Developer’s <strong>Guide</strong> Page 74<br />
Here we assume that we just used the previous example to read the one record at<br />
FFF8 in the LampLinc’s Non-PLC Link Database, and it contained A2 01 AABBCC FF<br />
1C 00. We will change the record to A2 01 010203 FF 1C 00, which will enroll the<br />
PLC. We will use an Extended Poke to poke only the 3 bytes 01 02 03 at address<br />
0FFA.<br />
PLC Sends LampLinc Responds<br />
Set Address MSB to 0F OK<br />
From Address 01 02 03 (PLC) A1 A2 A3 (LampLinc)<br />
To Address A1 A2 A3 (LampLinc) 01 02 03 (PLC)<br />
Flags 0F (Direct Message) 2F (Direct ACK Message)<br />
Command 1 28 (Set Address MSB) 28 (Set Address MSB)<br />
Command 2 0F (MSB of 0x0FF8) 0F (MSB of 0x0FF8)<br />
Poke Extended at Address 0FFA OK<br />
From Address 01 02 03 (PLC) A1 A2 A3 (LampLinc)<br />
To Address A1 A2 A3 (LampLinc) 01 02 03 (PLC)<br />
Flags 1F (Direct Extended Message) 3F (Direct ACK Extended Message)<br />
Command 1 29 (Poke) 29 (Poke)<br />
Command 2 FA (LSB of 0x0FFA) FA (LSB of 0x0FFA)<br />
User Data 03 01 02 03 00 00 00 00 00 00 00 00 00 00 XX XX XX XX XX XX XX XX XX XX XX XX XX XX<br />
Note that the first byte of the User Data field is the number of bytes to poke.<br />
October 14, 2005 © 2005 Smarthome Technology
<strong>INSTEON</strong> Device Classes<br />
Developer’s <strong>Guide</strong> Page 75<br />
The number of different kinds of devices that can be connected to an <strong>INSTEON</strong><br />
network is virtually unlimited. Rather than relying on an elaborate scheme for<br />
discovery of device capabilities, <strong>INSTEON</strong>’s designers opted for a very simple, yet<br />
expandable method for devices to identify themselves—they Broadcast a SET Button<br />
Pressed message containing device classification information. This information, the<br />
Device Type, Device Attributes, and Firmware Revision, appears in fixed-length fields<br />
within the Broadcast message.<br />
A 16-bit number identifies an <strong>INSTEON</strong> Device Type. See the <strong>INSTEON</strong> Device Type<br />
Summary Table for a list of currently defined Device Types.<br />
Device Identification Broadcast<br />
<strong>INSTEON</strong> devices identify themselves to other devices on an <strong>INSTEON</strong> network by<br />
sending a SET Button Pressed Broadcast message. This message contains a number<br />
of fields that describe the product type and capabilities.<br />
A 16-bit Device Type field appears in the most significant 2 bytes of the To Address<br />
field, followed by the Firmware Revision in the least significant byte. A Device<br />
Attributes byte appears in the Command 2 field.<br />
<strong>INSTEON</strong> SET Button Pressed Broadcast Message<br />
From<br />
Address<br />
To Address Message<br />
Flags<br />
Command 1 Command 2<br />
3 bytes 3 bytes 1 byte 1 byte 1 byte<br />
Device Type<br />
2 bytes 1 byte<br />
Device Type Firmware<br />
Revision<br />
1000xxxx SET Button<br />
Pressed Slave<br />
(0x01) or SET<br />
Button Pressed<br />
Master (0x03)<br />
Device Attributes<br />
Each <strong>INSTEON</strong> device contains a 2-byte Device Type identifier, which allows for<br />
65,536 different possible Device Types. Smarthome assigns these numbers to<br />
device manufacturers. Currently, Types are being assigned sequentially. See the<br />
<strong>INSTEON</strong> Device Type Summary Table for a list of currently defined Device Types.<br />
Designers who wish to develop <strong>INSTEON</strong>-enabled products should contact<br />
Smarthome at info@insteon.net for more information.<br />
Device Attributes<br />
When an <strong>INSTEON</strong> device identifies itself by sending out a SET Button Pressed<br />
Broadcast message, the message includes a Device Attributes byte in the Command<br />
2 field. Although currently unused, this byte can contain individual bit flags that<br />
could be interpreted differently for each Device Type.<br />
October 14, 2005 © 2005 Smarthome Technology
Firmware Revision<br />
Developer’s <strong>Guide</strong> Page 76<br />
An <strong>INSTEON</strong> device’s firmware revision number appears in the least significant byte<br />
of the To Address field of a SET Button Pressed Broadcast message. The high nibble<br />
(4 bits) gives the major revision number and the low nibble gives the minor revision.<br />
<strong>INSTEON</strong> Device Type Summary Table<br />
These are the currently defined <strong>INSTEON</strong> Device Types.<br />
Device<br />
Type<br />
Product<br />
0x0000 Smarthome PowerLinc V2 Controller<br />
0x0001 ⇒<br />
0x0003<br />
Reserved<br />
0x0004 Smarthome ControLinc V2<br />
0x0005 Smarthome RF RemoteLinc<br />
0x0006 ⇒<br />
0x00FF<br />
Reserved<br />
0x0100 Smarthome LampLinc V2 Dimmer<br />
0x0101 Smarthome SwitchLinc V2 Dimmer<br />
0x0102 ⇒<br />
0x0108<br />
Reserved<br />
0x0109 Smarthome KeypadLinc V2<br />
0x010A ⇒<br />
0x0113<br />
Reserved<br />
0x0114 Smarthome SwitchLinc V2 Companion<br />
0x0115 ⇒<br />
0x0208<br />
Reserved<br />
0x0209 Smarthome ApplianceLinc V2<br />
0x020A Smarthome SwitchLinc V2 Relay<br />
0x020B ⇒<br />
0xFFFF<br />
Reserved<br />
October 14, 2005 © 2005 Smarthome Technology
<strong>INSTEON</strong> Device Linking<br />
Developer’s <strong>Guide</strong> Page 77<br />
When a user adds a new device to an <strong>INSTEON</strong> network, the newcomer device joins<br />
the network automatically, in the sense that it can hear <strong>INSTEON</strong> messages and will<br />
repeat 1 them automatically according to the <strong>INSTEON</strong> protocol. So, no user<br />
intervention is needed to establish an <strong>INSTEON</strong> network of communicating devices.<br />
However, for one <strong>INSTEON</strong> device to control other <strong>INSTEON</strong> devices, the devices<br />
must be logically linked together. <strong>INSTEON</strong> provides two very simple methods for<br />
linking devices—manual linking using button pushes, and electronic linking using<br />
<strong>INSTEON</strong> messages.<br />
<strong>INSTEON</strong> Groups<br />
During linking, users create associations between events that can occur in an<br />
<strong>INSTEON</strong> Controller, such as a button press or a timed event, and the actions of a<br />
Group of one or more Responders. This section defines Groups and Links and gives<br />
Examples of Groups.<br />
Groups and Links<br />
A Group is a set of logical Links between <strong>INSTEON</strong> devices. A Link is an association<br />
between a Controller and a Responder or Responders. Controllers originate Groups,<br />
and Responders join Groups.<br />
Internally, in an <strong>INSTEON</strong> Link Database maintained by <strong>INSTEON</strong> devices, a Group<br />
ID consists of 4 bytes—the 3-byte address of the Controller, and a 1-byte Group<br />
Number. A Controller assigns Group Numbers as needed to the various physical or<br />
logical events that it supports. For example, a single press of a certain button could<br />
send commands to one Group, and a double press of the same button could send<br />
commands to another Group. The Controller determines which commands are sent<br />
to which Groups.<br />
A Group can have one or many members, limited only by the memory available for<br />
the Link Database.<br />
Examples of Groups<br />
A device configured as a wall switch with a paddle could be designed to support one,<br />
two, or three Groups, as shown in the following examples.<br />
One Group<br />
Controller Event Group Action of Group Responders<br />
Tap Top 1 Turn On<br />
Tap Bottom 1 Turn Off<br />
Hold Top 1 Brighten<br />
Hold Bottom 1 Dim<br />
October 14, 2005 © 2005 Smarthome Technology
Two Groups<br />
Developer’s <strong>Guide</strong> Page 78<br />
Controller Event Group Action of Group Responders<br />
Tap Top 1 Turn On<br />
Tap Top Again 1 Turn Off<br />
Tap Bottom 2 Turn On<br />
Tap Bottom Again 2 Turn Off<br />
Three Groups<br />
Controller Event Group Action of Group Responders<br />
Tap Top 1 Turn On<br />
Tap Bottom 1 Turn Off<br />
Double Tap Top 2 Turn On<br />
Double Tap Bottom 2 Turn Off<br />
Triple Tap Top 3 Turn On<br />
Triple Tap Bottom 3 Turn Off<br />
October 14, 2005 © 2005 Smarthome Technology
Developer’s <strong>Guide</strong> Page 79<br />
Methods for Linking <strong>INSTEON</strong> Devices<br />
There are two ways to create links among <strong>INSTEON</strong> devices, Manual Linking and<br />
Electronic Linking. This section also gives an Example of an <strong>INSTEON</strong> Linking<br />
Session.<br />
Manual Linking<br />
Easy setup is very important for products sold to a mass market. <strong>INSTEON</strong> devices<br />
can be linked together very simply:<br />
• Push and hold for 10 seconds the button that will control an <strong>INSTEON</strong> device.<br />
• Push and hold a button on the <strong>INSTEON</strong> device to be controlled.<br />
This kind of manual linking implements a form of security. Devices cannot be probed<br />
by sending messages to discover their addresses—a user must have physical<br />
possession of <strong>INSTEON</strong> devices in order to link them together.<br />
Designers are free to add to this basic linking procedure. For example, when<br />
multiple devices are being linked to a single button on a Controller, a multilink mode<br />
could enable a user to avoid having to press and hold the button for 10 seconds for<br />
each new device.<br />
There must also be procedures to unlink devices from a button, and ways to clear<br />
links from buttons in case devices linked to them are lost or broken. See the<br />
<strong>INSTEON</strong> Link Database section below for more information on this point.<br />
Electronic Linking<br />
As the example below shows (see Example of an <strong>INSTEON</strong> Linking Session), linking<br />
is actually accomplished by sending <strong>INSTEON</strong> messages, so a PC or other device can<br />
create links among devices if the device addresses are known and if devices can<br />
respond to the necessary commands.<br />
To maintain security, PC-<strong>INSTEON</strong> interface devices such as Smarthome’s<br />
PowerLinc V2 Controller (PLC) mask the two high bytes of the address fields in<br />
<strong>INSTEON</strong> messages received from unknown devices. Devices are only known if there<br />
is a link to the device stored in the Link Database of the PLC, or if the message’s To<br />
Address matches that of the PLC. Such links must have been previously established<br />
by manual button pushing or else by manually typing in the addresses of linked<br />
devices (see Masking Non-linked Network Traffic, below).<br />
October 14, 2005 © 2005 Smarthome Technology
Developer’s <strong>Guide</strong> Page 80<br />
Example of an <strong>INSTEON</strong> Linking Session<br />
This section outlines the message exchange that occurs when a Controller and<br />
Responder set up a link relationship. In this scenario, a Smarthome ControLinc V2<br />
is the Controller, and a Smarthome LampLinc V2 is the Responder. Numbers are in<br />
hexadecimal.<br />
Message 1 ControLinc: “I’m looking for Group members”<br />
00 00 CC 00 04 0C 8F 03 00<br />
ControLinc, with address of 00 00 CC, sends a SET Button Pressed Master<br />
Broadcast message indicating it is now listening for Responders to be added to<br />
Group 1.<br />
From Address 00 00 CC (ControLinc)<br />
To Address<br />
Device Type 00 0A (ControLinc)<br />
Firmware Version 0C<br />
Flags 8F (Broadcast Message,<br />
3 Max Hops, 3 Hops Left)<br />
Command 1 03 (SET Button Pressed Master)<br />
Command 2 Device Attributes 00 (Not used)<br />
Message 2 LampLinc: “I’ll join your Group”<br />
00 00 AA 01 00 30 8F 01 00<br />
LampLinc, with address of 00 00 AA, sends a SET Button Pressed<br />
Slave Broadcast message. When the ControLinc hears this, it will respond<br />
with a message to join Group 1.<br />
From Address 00 00 AA (LampLinc)<br />
To Address<br />
Device Type 00 02 (LampLinc)<br />
Firmware Version 30<br />
Flags 8F (Broadcast Message,<br />
3 Max Hops, 3 Hops Left)<br />
Command 1 01 (SET Button Pressed Slave)<br />
Command 2 Device Attributes 00 (Not used)<br />
Message 3 ControLinc: “Okay, join Group 1”<br />
00 00 CC 00 00 AA 0F 01 01<br />
ControLinc (00 00 CC) sends message to LampLinc (00 00 AA) to join Group 1.<br />
From Address 00 00 CC (ControLinc)<br />
To Address 00 00 AA (LampLinc)<br />
Flags 0F (Direct Message,<br />
3 Max Hops, 3 Hops Left)<br />
Command 1 01 (Assign to Group)<br />
Command 2 01 (Group 1)<br />
October 14, 2005 © 2005 Smarthome Technology
Developer’s <strong>Guide</strong> Page 81<br />
Message 4 LampLinc: “I joined Group 1”<br />
00 00 AA 00 00 CC 2F 01 01<br />
LampLinc (00 00 31) sends ACK to ControLinc (00 00 10).<br />
From Address 00 00 AA (LampLinc)<br />
To Address 00 00 CC (ControLinc)<br />
Flags 2F (ACK of Direct Message,<br />
3 Max Hops, 3 Hops Left)<br />
Command 1 01 (Assign to Group)<br />
Command 2 01 (Group 1)<br />
Example of <strong>INSTEON</strong> Group Conversation<br />
This example illustrates how messages are passed from device to device in a group.<br />
In this scenario, a Smarthome ControLinc V2 linked to two Smarthome LampLinc<br />
V2 Dimmers in Group 1 commands them to turn on. Numbers are in hexadecimal.<br />
Note that the Group Broadcast message (which both LampLinc Dimmers should<br />
respond to immediately) is followed by an acknowledged Group Cleanup message to<br />
each LampLinc Dimmer (in case they didn’t get the Broadcast).<br />
Message 1 ControLinc: “Group 1, turn on”<br />
00 00 CC 00 00 01 CF 11 00<br />
ControLinc, with address of 00 00 CC, sends a Group Broadcast message to<br />
Group 1, with a command of On.<br />
From Address 00 00 CC (ControLinc)<br />
To Address<br />
Unused 00 00<br />
Group Number 01<br />
Flags CF (Group Broadcast Message,<br />
3 Max Hops, 3 Hops Left)<br />
Command 1 11 (On)<br />
Command 2 00 (Unused)<br />
Message 2 ControLinc: “LampLinc A, turn on”<br />
00 00 CC 00 00 AA 4F 11 01<br />
ControLinc (00 00 CC) sends a Group Cleanup message to<br />
LampLinc A (00 00 AA) in Group 1, with a command of On.<br />
From Address 00 00 CC (ControLinc)<br />
To Address 00 00 AA (LampLinc A)<br />
Flags 4F (Group Cleanup Message,<br />
3 Max Hops, 3 Hops Left)<br />
Command 1 11 (On)<br />
Command 2 Group Number 01<br />
October 14, 2005 © 2005 Smarthome Technology
Developer’s <strong>Guide</strong> Page 82<br />
Message 3 LampLinc A: “I turned on”<br />
00 00 AA 00 00 CC 2F 11 01<br />
LampLinc A (00 00 AA) sends ACK to ControLinc (00 00 CC).<br />
From Address 00 00 AA (LampLinc A)<br />
To Address 00 00 CC (ControLinc)<br />
Flags 2F (ACK of Direct Message,<br />
3 Max Hops, 3 Hops Left)<br />
Command 1 11 (On)<br />
Command 2 Group Number 01<br />
Message 4 ControLinc: “LampLinc B, turn on”<br />
00 00 CC 00 00 BB 4F 11 01<br />
ControLinc (00 00 CC) sends a Group Cleanup message to<br />
LampLinc B (00 00 BB) in Group 1, with a command of On.<br />
From Address 00 00 CC (ControLinc)<br />
To Address 00 00 BB (LampLinc B)<br />
Flags 4F (Group Cleanup Message,<br />
3 Max Hops, 3 Hops Left)<br />
Command 1 11 (On)<br />
Command 2 Group Number 01<br />
Message 5 LampLinc B: “I turned on”<br />
00 00 BB 00 00 CC 2F 11 01<br />
LampLinc B (00 00 BB) sends ACK to ControLinc (00 00 CC).<br />
From Address 00 00 BB (LampLinc B)<br />
To Address 00 00 CC (ControLinc)<br />
Flags 2F (ACK of Direct Message,<br />
3 Max Hops, 3 Hops Left)<br />
Command 1 11 (On)<br />
Command 2 Group Number 01<br />
An <strong>INSTEON</strong> Controller will send Group Cleanup commands to all Responder devices<br />
in a Group, unless other <strong>INSTEON</strong> traffic interrupts the cleanup, in which case the<br />
Group Cleanups will stop.<br />
October 14, 2005 © 2005 Smarthome Technology
<strong>INSTEON</strong> Link Database<br />
Developer’s <strong>Guide</strong> Page 83<br />
Every <strong>INSTEON</strong> device stores a Link Database in nonvolatile memory, representing<br />
Controller/Responder relationships with other <strong>INSTEON</strong> devices. Controllers know<br />
which Responders they are linked to, and Responders know which Controllers they<br />
are linked to. Link data is therefore distributed among devices in an <strong>INSTEON</strong><br />
network.<br />
If a Controller is linked to a Responder, and the Responder is removed from the<br />
network without updating the Controller’s Link Database, then the Controller will<br />
retry messages intended for the missing Responder. The retries, which are<br />
guaranteed to fail, will add unnecessary traffic to the network. It is therefore very<br />
important for users to unlink <strong>INSTEON</strong> Responder devices from Controllers when<br />
unused Responders are removed. Unlinking is normally accomplished in the same<br />
way as linking—press and hold a button on the Controller, then press and hold a<br />
button on the Responder.<br />
Because lost or broken Responder devices cannot be unlinked using a manual<br />
unlinking procedure, Controllers must also have an independent method for unlinking<br />
missing Responders. Providing a ‘factory reset’ procedure for a single Controller<br />
button, or for the entire Controller all at once, is common.<br />
When a Controller is removed from the network, it should likewise be unlinked from<br />
all of its Responder devices before removal, or else the Link Databases in the<br />
Responders will be cluttered up with obsolete links. A ‘factory reset’ should be<br />
provided for Responder devices for this purpose.<br />
There are two forms of Link Database Record, one for SALad-enabled devices such<br />
as Smarthome’s PowerLinc V2 Controller (PLC), and another for non-PLC devices.<br />
This section describes both.<br />
In This Section<br />
PLC Link Database<br />
Explains the contents of the Link Database for the Smarthome PowerLinc V2<br />
Controller.<br />
Non-PLC Link Database<br />
Gives the layout of Link Database Records for other <strong>INSTEON</strong> devices.<br />
October 14, 2005 © 2005 Smarthome Technology
PLC Link Database<br />
Developer’s <strong>Guide</strong> Page 84<br />
The PLC Link Database starts at the top of external (serial) EEPROM and grows<br />
downward. Because of the way Flat Memory Addressing works, top of memory can<br />
always be found at 0xFFFF.<br />
Each PLC Link Database Record is 8 bytes long, so the first physical record starts at<br />
0xFFF8, the second physical record starts at 0xFFF0, and so on. The Link Database<br />
starts out containing a minimum of 128 physical records, so it occupies the top 1024<br />
bytes of external EEPROM. The Link Database can grow larger than 1024 bytes, until<br />
it bumps up against the SALad application that grows upward from the bottom of<br />
EEPROM.<br />
In what follows, the 3-byte <strong>INSTEON</strong> Address contained in a record is called the<br />
Device ID. The high byte (MSB) of the Device ID is ID2, the middle byte is ID1, and<br />
the low byte (LSB) is ID0. MSb and LSb refer to most and least significant bits,<br />
respectively. All addresses refer to the Flat Memory Map.<br />
The PLC Link Database is organized as a set of 128 threads, where each thread is a<br />
(forward) linked list. The address of the first record in a thread is calculated from<br />
the 7 MSbs of ID0 of the Device ID, as described in the table.<br />
Field Length<br />
(bytes)<br />
Record<br />
Control<br />
Description<br />
PLC Link Database Record Format<br />
2 76543210 76543210 Class:<br />
XXXXXXXX XXXXXXXX 00 Deleted (ID0 LSb indicates end of DB)<br />
Link----++++++++--+++++||| 01 Other (extended class)<br />
Class------------------++| 10 Slave (<strong>INSTEON</strong> Responder)<br />
ID0_LSb------------------+ 11 Master (<strong>INSTEON</strong> Controller)<br />
Link gives the 13 MSbs of the 16-bit address of the next record in this one of 128 possible<br />
database threads. The 3 LSbs of this address are 0.<br />
If the 8 MSbs of Link are 0, this is the end of the thread.<br />
If the Class is 00 and ID0_LSb is 1, then this is the last physical record in the database.<br />
The 16-bit address of the first record in a thread is computed from ID0 by shifting ID0 left 2<br />
(i.e. multiplying ID0 by 4), complementing the 16-bit result, then setting the 3 LSbs to 0.<br />
Class indicates whether the record is available (Deleted), for an <strong>INSTEON</strong> Controller (Master),<br />
for an <strong>INSTEON</strong> Responder (Slave), or user-defined (Other).<br />
ID0 LSb is the LSb of ID0 in the Device ID.<br />
ID1 1 Middle byte of the Device ID<br />
ID2 1 High (MSB) byte of the Device ID<br />
Group 1 Group Number (for <strong>INSTEON</strong> Groups)<br />
Data 1 1 Link-specific data (e.g. On-Level)<br />
Data 2 1 Link-specific data (e.g. Ramp Rates, Setpoints, etc.)<br />
Data 3 1 Unused<br />
If you are searching the database for a given Device ID, calculate the starting<br />
address for the thread using the given ID’s low byte, then follow the links until ID1,<br />
ID2, and ID0_LSb match.<br />
October 14, 2005 © 2005 Smarthome Technology
Developer’s <strong>Guide</strong> Page 85<br />
If you are searching the database for something else, such as all records with a<br />
given Group Number and/or all records in a given Class, then you will have to look at<br />
all 128 threads. As you increment through the threads, keep a Thread_Index<br />
counter running from 0x00 to 0x7F. To recover ID0 of the Device ID in a given<br />
record, multiply Thread_Index by 2 and add in the ID0_LSb bit.<br />
The above information should be sufficient for you to write routines that can<br />
manipulate the PLC Link Database directly using IBIOS Serial Commands or<br />
<strong>INSTEON</strong> Commands. Be sure that the database doesn’t grow too large as you add<br />
records, and you might want to ‘de-frag’ the database to recover space as you delete<br />
records.<br />
There are utility routines in the SALad coreApp Program that you can use for dealing<br />
with the PLC Link Database. Using coreApp routines is far easier than writing your<br />
own.<br />
During SALad code development, you can directly read and write records to a PLC<br />
Link Database if you are using the SALad Integrated Development Environment<br />
(IDE). See the PLC Database section of the SALad Integrated Development<br />
Environment User’s <strong>Guide</strong>.<br />
October 14, 2005 © 2005 Smarthome Technology
Non-PLC Link Database<br />
Developer’s <strong>Guide</strong> Page 86<br />
Non-PLC devices, such as the ControLinc V2, SwitchLinc V2, LampLinc V2, or<br />
ApplianceLinc V2, contain a Link Database whose records are stored sequentially,<br />
as opposed to linked-list storage in the PLC. Nevertheless, the data contained in a<br />
given record is similar.<br />
The Non-PLC Link Database starts at the top of external (serial) EEPROM and grows<br />
downward. In most Non-PLC <strong>INSTEON</strong> devices, top of memory is 0x0FFF. Each<br />
Non-PLC Link Database Record is 8 bytes long, so the first record starts at 0x0FF8,<br />
the second record starts at 0x0FF0, and so on.<br />
In the table, the 3-byte <strong>INSTEON</strong> Address contained in a record is called the Device<br />
ID.<br />
Field Length<br />
(bytes)<br />
Description<br />
Flags 1 Link Control Flags:<br />
Non-PLC Link Database Record Format<br />
Bit 7: 1 = Record is in use, 0 = Record is available<br />
Bit 6: 1 = Controller (Master) of Device ID, 0 = Responder to (Slave of) Device ID<br />
Bit 5: 1 = ACK Required, 0 = No ACK Required (currently always set to 1)<br />
Bit 4: Reserved<br />
Bit 3: Reserved<br />
Bit 2: Reserved<br />
Bit 1: 1 = Record has been used before (‘high-water’ mark)<br />
Bit 0: Unused<br />
Group 1 Group Number<br />
ID 3 Device ID<br />
Data 1 1 Link-specific data (e.g. On-Level)<br />
Data 2 1 Link-specific data (e.g. Ramp Rates, Setpoints, etc.)<br />
Data 3 1 Unused<br />
October 14, 2005 © 2005 Smarthome Technology
<strong>INSTEON</strong> Extended Messages<br />
Developer’s <strong>Guide</strong> Page 87<br />
Designers are free to devise all kinds of meanings for the User Data that can be<br />
exchanged among devices using <strong>INSTEON</strong> Extended messages. For example, many<br />
<strong>INSTEON</strong> devices include an interpreter for an application language, called SALad,<br />
which is compiled into token strings. SALad token string programs can be<br />
downloaded into devices (and they can also be debugged) using Extended messages<br />
(see SALad Applications, below).<br />
For applications that must be secure, such as door locks and security systems,<br />
Extended messages can contain encrypted data. See Encryption within Extended<br />
Messages, below for more information.<br />
If an application needs to transport more than 14 bytes of User Data, then it can use<br />
multiple Extended messages. Each Extended message can act as a packet, with the<br />
complete User Data reassembled after all packets are received. Bear in mind,<br />
however, that <strong>INSTEON</strong> was not designed for unrestricted data communications—<br />
instead, it is optimized for simplicity and reliability. Designers are encouraged to<br />
minimize the use of <strong>INSTEON</strong> to handle large amounts of data.<br />
October 14, 2005 © 2005 Smarthome Technology
<strong>INSTEON</strong> Security<br />
Developer’s <strong>Guide</strong> Page 88<br />
<strong>INSTEON</strong> network security is maintained at two levels. Linking Control ensures that<br />
users cannot create links that would allow them to control their neighbors’ <strong>INSTEON</strong><br />
devices, even though those devices may be repeating each other’s messages.<br />
Encryption within Extended Messages permits completely secure communications for<br />
applications that require it.<br />
Linking Control<br />
<strong>INSTEON</strong> enforces Linking Control by requiring that users have Physical Possession<br />
of Devices in order to create links, and by Masking Non-linked Network Traffic when<br />
messages are relayed outside the <strong>INSTEON</strong> network itself.<br />
Physical Possession of Devices<br />
Firmware in <strong>INSTEON</strong> devices prohibits them from identifying themselves to other<br />
devices unless a user physically presses a button on the device. That is why the<br />
Command in the network identification Broadcast message is called SET Button<br />
Pressed. As shown above in the section Example of an <strong>INSTEON</strong> Linking Session, a<br />
user has to push buttons on both the Controller device and the Responder device in<br />
order to establish a link between them. A Responder will not act on commands from<br />
an unlinked Controller.<br />
Linking by sending <strong>INSTEON</strong> messages requires knowledge of the 3-byte addresses<br />
of <strong>INSTEON</strong> devices. These addresses, unique for each device, are assigned at the<br />
factory and displayed on printed labels attached to the device. Users who have<br />
physical possession of a device can read the device address from the label and<br />
manually enter it when prompted by a computer program.<br />
Masking Non-linked Network Traffic<br />
As described in the section Interfacing to an <strong>INSTEON</strong> Network, above, there can be<br />
many kinds of <strong>INSTEON</strong> devices, called Bridges, that connect an <strong>INSTEON</strong> network<br />
to the outside world. But since an <strong>INSTEON</strong> Bridge is itself just another <strong>INSTEON</strong><br />
device, it must be linked to other devices on the <strong>INSTEON</strong> network in order to<br />
exchange messages with them. A user must establish these links in the same way<br />
as for any other <strong>INSTEON</strong> device—by pushing buttons or by typing in addresses.<br />
Smarthome’s PowerLinc Controller (PLC) is an example of an <strong>INSTEON</strong>-certified<br />
Bridge device that monitors <strong>INSTEON</strong> traffic and relays it to a computer via a serial<br />
link. For security, the PLC’s firmware masks the all but the two low-bytes of the<br />
From Address and To Address fields of <strong>INSTEON</strong> messages unless the traffic is from<br />
an <strong>INSTEON</strong> device already linked to the PLC, or the traffic is from a device that<br />
already knows the address of the PLC. In this way, software can take into account<br />
the existence of <strong>INSTEON</strong> traffic without users being able to discover the addresses<br />
of devices that they never had physical access to.<br />
To avoid ‘spoofing,’ where an attacker poses as someone else (by causing the PLC to<br />
send messages with bogus From Addresses), the PLC’s firmware always inserts the<br />
true PLC ID number in the From Address field of messages that it sends.<br />
October 14, 2005 © 2005 Smarthome Technology
Developer’s <strong>Guide</strong> Page 89<br />
Encryption within Extended Messages<br />
For applications such as door locks and security systems, <strong>INSTEON</strong> Extended<br />
messages can contain encrypted payloads. Possible encryption methods include<br />
rolling-code, managed-key, and public-key algorithms. In keeping with <strong>INSTEON</strong>’s<br />
hallmark of simplicity, rolling-code encryption, as used by garage door openers and<br />
radio keyfobs for cars, is the method preferred by Smarthome. The encryption<br />
method that will be certified as the <strong>INSTEON</strong> standard is currently under<br />
development.<br />
October 14, 2005 © 2005 Smarthome Technology
<strong>INSTEON</strong> BIOS (IBIOS)<br />
Developer’s <strong>Guide</strong> Page 90<br />
The <strong>INSTEON</strong> Basic Input/Output System (IBIOS) implements the basic functionality<br />
of <strong>INSTEON</strong> devices like Smarthome’s PowerLinc V2 Controller (PLC). Built on a<br />
flat 16-bit address space, this firmware includes an <strong>INSTEON</strong> Engine that handles<br />
low-level <strong>INSTEON</strong> messaging, PLC event generation, USB or RS232 serial<br />
communications, IBIOS Serial Command processing, a software realtime clock, a<br />
SALad language interpreter, and various other functions.<br />
The SALad language interpreter runs SALad applications that can stand alone or<br />
interface serially with other computing devices. The Smarthome PowerLinc<br />
Controller comes from the factory with a pre-installed SALad coreApp Program that<br />
provides onboard event handling, <strong>INSTEON</strong> device linking, and many other useful<br />
functions not supported by IBIOS. But even without a SALad program like coreApp<br />
running, IBIOS offers a sophisticated serial interface to the outside world.<br />
This section explains what the <strong>INSTEON</strong> Engine does, what IBIOS Events occur, how<br />
serial communications works, how to use IBIOS Serial Commands directly, and other<br />
features of IBIOS. See the SALad Language Documentation section for complete<br />
information on writing and running SALad programs.<br />
In This Section<br />
IBIOS Flat Memory Model<br />
Describes how physical memory is mapped into a single 16-bit address space and<br />
gives a table of all important memory locations.<br />
IBIOS Events<br />
Lists the Events that IBIOS generates and explains how they work.<br />
IBIOS Serial Communication Protocol and Settings<br />
Describes the serial communication protocol, the port settings for an RS232 link,<br />
and how to use a USB link.<br />
IBIOS Serial Commands<br />
Lists the IBIOS Serial Commands, describes what they do, and gives examples of<br />
how to use them.<br />
IBIOS <strong>INSTEON</strong> Engine<br />
Discusses the functionality of the <strong>INSTEON</strong> Engine.<br />
IBIOS Software Realtime Clock/Calendar<br />
Describes how to use the software realtime clock/calendar.<br />
IBIOS X10 Signaling<br />
Explains usage of the X10 powerline interface.<br />
IBIOS Input/Output<br />
Gives details on the Pushbutton input and LED flasher.<br />
IBIOS Remote Debugging<br />
Describes how SALad programs can be remotely debugged using IBIOS.<br />
IBIOS Watchdog Timer<br />
Describes how the watchdog timer works.<br />
October 14, 2005 © 2005 Smarthome Technology
IBIOS Flat Memory Model<br />
Developer’s <strong>Guide</strong> Page 91<br />
All IBIOS memory, no matter what its physical address, is accessed using a flat 16bit<br />
address space. Microcontroller RAM, microcontroller internal (high-speed)<br />
EEPROM, external I 2 C serial (low-speed) EEPROM, and any other I 2 C chips are all<br />
mapped into this single 16-bit space.<br />
In This Section<br />
Flat Memory Addressing<br />
Describes how the various physical memory regions are mapped into one 16-bit<br />
address space, and how I 2 C addressing works.<br />
Flat Memory Map<br />
Gives a table of all important IBIOS memory locations.<br />
October 14, 2005 © 2005 Smarthome Technology
Flat Memory Addressing<br />
Developer’s <strong>Guide</strong> Page 92<br />
The 16-bit flat address space is broken up into two regions. The bottom 32K<br />
(0x0000 through 0x7FFF) is a fixed area that always maps to the same physical<br />
memory. The top 32K (0x8000 through 0xFFFF) is a variable area that maps to the<br />
physical memory of up to four different I 2 C chips provided in hardware, under control<br />
of the register I2C_Addr.<br />
The bottom 32K fixed area always contains the microcontroller RAM registers in<br />
addresses 0x0000 through 0x01FF, and microcontroller internal EEPROM in<br />
addresses 0x200 through 0x02FF. The remainder of the bottom 32K, from 0x0300<br />
through 0x7FFF, always maps to the physical memory of the primary external I 2 C<br />
serial EEPROM chip from 0x0000 through 0x7CFF. (The primary external I 2 C serial<br />
chip has all of its chip-select pins tied low in hardware.)<br />
To choose which of the four possible I 2 C chips to map to the top 32K of the flat<br />
address space, set the top 7 bits of the I2C_Addr register. The top 4 bits (bits 7 – 4)<br />
will match the I 2 C address burned into the I 2 C chip by the manufacturer. Bits 3 and<br />
2 will match the way the chip-select pins of the I 2 C chip are wired in hardware. Set<br />
the bit to 0 for a pin that is tied low, or to 1 for a pin that is tied high. The third<br />
chip-select pin must always be tied low in hardware so that bit 1 of the I2C_Addr<br />
register can be used to indicate whether the I 2 C chip uses 8-bit or 16-bit addressing.<br />
(A chip with no more than 256 memory locations, such as a realtime clock chip, will<br />
normally use 8-bit addressing, but chips with more than 256 memory locations, such<br />
as serial EEPROMs, must use 16-bit addressing.)<br />
While top 7 bits of the I2C_Addr register uniquely identify which I 2 C chip to map into<br />
the top 32K of flat memory, the least-significant bit (the LSb, bit 0), selects whether<br />
the bottom 32K or the top 32K of this chip’s memory will appear in that space. If<br />
the I 2 C chip in question does not contain more than 32K of memory, it does not<br />
actually matter how the I2C_Addr register’s LSb is set. But if the I 2 C chip does<br />
contain more than 32K of memory, then setting the LSb to 0 will access the bottom<br />
32K, and setting the LSb to 1 will access any memory above 32K.<br />
Note that I 2 C chips that contain fewer than 32K addresses in power-of-two<br />
increments (e.g. 1K, 2K, 4K, 8K, or 16K chips) will have their available addresses<br />
repeated multiple times in the top 32K of flat memory. For example, an 8K chip will<br />
appear four times in the 32K space, and a 16K chip will appear twice.<br />
(Mathematically, if the chip contains 2^N addresses, and N is 15 or less, then the<br />
chip’s contents will be repeated 2^(15 – N) times in the top 32K of flat memory.)<br />
Overall Flat Memory Map<br />
Address Range Contents<br />
0x0000⇒0x01FF Microcontroller RAM Registers<br />
0x0200⇒0x02FF Microcontroller Hi speed EEPROM<br />
0x0300⇒0x7FFF Serial I 2 C EEPROM physical addresses 0x0000 through 0x7CFF<br />
0x8000⇒0xFFFF Varies depending on contents of register I2C_Addr<br />
I2C_Addr: xxxxxxx0 = I 2 C physical addresses 0x0000⇒0x7FFF<br />
I2C_Addr: xxxxxxx1 = I 2 C physical addresses 0x8000⇒0xFFFF<br />
October 14, 2005 © 2005 Smarthome Technology
I2C_Addr Register<br />
Bit Meaning<br />
7 (MSb)<br />
6<br />
5<br />
4<br />
3<br />
2<br />
Developer’s <strong>Guide</strong> Page 93<br />
I2C_Addr Register<br />
Top nibble of I 2 C Address burned into I 2 C chip by manufacturer.<br />
Top 2 of 3 chip-select pins tied high or low in hardware design.<br />
There can be a total of 4 I 2 C chips.<br />
1 3rd of 3 chip-select pins must be tied low in hardware design, so that IBIOS can use this bit as<br />
follows:<br />
0 = I 2 C chip uses 8-bit addressing (e.g. realtime clock chip).<br />
1 = I 2 C chip uses 16-bit addressing (e.g. serial EEPROM).<br />
0 (LSb) Defined by I 2 C spec as Read/Write bit, but used by IBIOS as follows:<br />
0 = bottom 32K of I 2 C chip is mapped to top 32K of flat memory.<br />
1 = top 32K of I 2 C chip is mapped to top 32K of flat memory.<br />
October 14, 2005 © 2005 Smarthome Technology
Flat Memory Map<br />
Address Register and Bits Description<br />
Developer’s <strong>Guide</strong> Page 94<br />
0x0024 NTL_CNT Count for SALad block mode operations<br />
0x0026 RD_H Remote Debugging breakpoint address MSB<br />
0x0027 RD_L Remote Debugging breakpoint address LSB<br />
0x0028 PC_H SALad Program Counter MSB<br />
0x0029 PC_L SALad Program Counter LSB<br />
0x002A DB_H Database Pointer MSB<br />
0x002B DB_L Database Pointer LSB<br />
0x002C NTL_SP_H Return Stack Pointer MSB<br />
0x002D NTL_SP_L Return Stack Pointer LSB<br />
0x0033 NTL_BUFFER Pointer to end of Timer Buffer, which begins at 0x0046. This<br />
8-bit pointer defaults to 0x4D to allow room for 4 timers which<br />
are 2 bytes each.<br />
0x0034 NTL_RND Random Number Register<br />
0x0035 NTL_REG_H High byte of Pointer to R0<br />
0x0036 NTL_REG_L Low byte of Pointer to R0<br />
0x0037 NTL_EVENT Event used to invoke SALad<br />
0x0038 ⇒<br />
0x003F<br />
NTL_EVNT0-<br />
NTL_EVNT7<br />
Static Event Queue<br />
0x0040 NTL_TIME_H Time-of-day alarm (minutes since midnight MSB)<br />
0x0041 NTL_TIME_L Time-of-day alarm (minutes since midnight LSB)<br />
0x0042 NTL_TICK Zero Crossing count down tick timer<br />
0x0046 ⇒<br />
NTL_BUFFER<br />
NTL_BUFFER<br />
⇒ NTL_SP<br />
NTL_SP ⇒<br />
0x006F<br />
NTL_TIMERS Timer Buffer; Starts at 0x0046<br />
NTL_REGS User Register Space<br />
NTL_STACK SALad Return Stack<br />
0x0074 TOKEN Currently executing SALad instruction token<br />
0x0075<br />
NTL_STAT SALad Status Register<br />
_DB_END 4 1=Enrollment database search reached end of database<br />
_DB_PASS 3 1=Enrollment database search successful<br />
_NTL_DZ 2 1=Divide by Zero<br />
_NTL_BO 1 1=Buffer Overrun<br />
October 14, 2005 © 2005 Smarthome Technology
Address Register and Bits Description<br />
0x0076<br />
0x0142<br />
0x0154<br />
Developer’s <strong>Guide</strong> Page 95<br />
_NTL_CY 0 1=Carry from Math and Test operations<br />
NTL_CONTROL SALad debugging control flags<br />
_RD_STEP<br />
_RD_HALT<br />
7<br />
6<br />
_RD_HALT _RD_STEP<br />
0 0 Normal execution<br />
0 1 Animation (Trace)<br />
1 0 Execution halted<br />
1 1 Single step requested<br />
_RD_BREAK 5 0=Range Check Mode, 1=Breakpoint Mode<br />
I_Control <strong>INSTEON</strong> result flags<br />
_I_DebugRpt 6 1=Enable <strong>INSTEON</strong> Debug Report<br />
_I_SendDirect 5 0=Send <strong>INSTEON</strong> from working buffer, 1=Send <strong>INSTEON</strong><br />
direct<br />
_I_Transmit 4 1=Request To Send <strong>INSTEON</strong><br />
_Repeat_On 1 1=Hops enabled<br />
Control General system control flags<br />
_Reset 7 1=request system reset<br />
_Watchdog 6 1=request watchdog reset<br />
_PDI 2 1=Daughter card interrupt occurred and has been serviced<br />
_NoEventRpt 1 1=Inhibit static event report<br />
_TAP_LAST 0 last state of push button<br />
0x0156 TAP_CNT Counts multiple SET Button taps<br />
0x0157 Tick Incremented from 0⇒120 every second<br />
0x0158 RTC_TIME_H Time since midnight in minutes (MSB, 0-1439)<br />
0x0159 RTC_TIME_L Time since midnight in minutes (LSB, 0-1439)<br />
0x015A RTC_YEAR Year (0-99)<br />
0x015B RTC_MON Month (1-12)<br />
0x015C RTC_DAY Day (1-31, month specific)<br />
0x015D RTC_DOW Day-of-Week bitmap (0SSFTWTM)<br />
0x015E RTC_HOUR Hour (0-23)<br />
0x015F RTC_MIN Minute (0-59)<br />
0x0160 RTC_SEC Second (0-59)<br />
0x0164 X10_RX X10 Receive Buffer<br />
October 14, 2005 © 2005 Smarthome Technology
Address Register and Bits Description<br />
0x0165 X10_TX X10 Transmit Buffer<br />
0x0166<br />
X10_FLAGS X10 Flags<br />
Developer’s <strong>Guide</strong> Page 96<br />
_X10_RTS 7 1=Request To Send<br />
_X10_TXEX 6 1=Start extended transmit after current command (for internal<br />
use)<br />
_X10_EXTENDED 5 1=Extended transfer in progress (Tx or Rx)<br />
_X10_COMBUF 4 1=Command, 0=Address (for internal use)<br />
_X10_TXCOMMAND 3 1=Command, 0=Address for transmit<br />
_X10_RXCOMMAND 2 1=Command, 0=Address for receive<br />
_X10_VALID 1 1=X10 receive valid<br />
_X10_ENABLED 0 1=X10 active (for internal use)<br />
0x0168 LED_MODE Bitmap defines flashing pattern for LED<br />
1=On, 0=Off<br />
0x0169 LED_TMR Duration of LED flashing in seconds<br />
0x016A LED_DLY Period between each flash. Defaults to 5, which is 1/8 second<br />
per bit in LED_MODE.<br />
0x016B<br />
0x016F<br />
RS_CONTROL Control flags for serial command interpreter<br />
_RS_ComReset 7<br />
_RS_ComLimit2 6<br />
_RS_ComLimit1 5<br />
These are used for serial command time limit. This limits how<br />
long a command remains active in SALad. This prevents the<br />
serial engine from locking you out if SALad receives a corrupt<br />
command (non-native serial command). Default time limit is<br />
two seconds. To disable, clear bits 5⇒7.<br />
_RS_AppLock 3 1=Enable overwriting of SALad code from 0x0200 to end of<br />
SALad App given in 0x0216 and 0x0217<br />
_RS_ComDisable 2 1=core command processing disabled<br />
_RS_ComActive 1 1=command active for SALad processing (Non-native serial<br />
command)<br />
_RS_02 0 1=02 received for command start<br />
EventMask Mask to enable or disable events<br />
_EM_BtnTap 7 1=enabled<br />
_EM_BtnHold 6 1=enabled<br />
_EM_BtnRel 5 1=enabled<br />
_EM_TickTimer 4 1=enabled<br />
_EM_Alarm 3 1=enabled<br />
October 14, 2005 © 2005 Smarthome Technology
Address Register and Bits Description<br />
_EM_Midnight 2 1=enabled<br />
_EM_2AM 1 1=enabled<br />
_EM_RX 0 1=enabled<br />
Developer’s <strong>Guide</strong> Page 97<br />
0x017D Address of I 2 I2C_ADDR<br />
C device; bit 0 controls 0x8000 ⇒ 0xFFFF of flat<br />
model, 1=hi region, 0=low region<br />
0x01A0 DB_FLAGS Database search mode bitmap<br />
0x01A1 DB_0 Database ID_H; (<strong>INSTEON</strong> construction buffer) From<br />
Address_H; ignored for <strong>INSTEON</strong> message construction<br />
0x01A2 DB_1 Database ID_M; (<strong>INSTEON</strong> construction buffer) From<br />
Address_M; ignored for <strong>INSTEON</strong> message construction<br />
0x01A3 DB_2 Database ID_L; (<strong>INSTEON</strong> construction buffer) From<br />
Address_L; ignored for <strong>INSTEON</strong> message construction<br />
0x01A4 DB_3 Database Command 1; (<strong>INSTEON</strong> construction buffer) To<br />
Address_H<br />
0x01A5 DB_4 Database Command 2; (<strong>INSTEON</strong> construction buffer) To<br />
Address_M<br />
0x01A6 DB_5 Database Group Number; (<strong>INSTEON</strong> construction buffer) To<br />
Address_L<br />
0x01A7 DB_6 Database State; (<strong>INSTEON</strong> construction buffer) Message Flags<br />
0x01A8 DB_7 Message Command 1; (<strong>INSTEON</strong> construction buffer)<br />
Command 1<br />
0x01A9 DB_8 Message Command 2; (<strong>INSTEON</strong> construction buffer)<br />
Command 2<br />
0x01AA DB_9<br />
0x01AB DB_A<br />
0x01AC RxFrom0 Receive “From” address high byte<br />
0x01AD RxFrom1 Receive “From” address middle byte<br />
0x01AE RxFrom2 Receive “From” address low byte<br />
0x01AF RxTo0 Receive “To” address high byte<br />
0x01B0 RxTo1 Receive “To” address middle byte<br />
0x01B1 RxTo2 Receive “To” address low byte<br />
0x01B2<br />
RxExtRpt Receive Control Flags<br />
_RxBroadcastBit 7 Broadcast Message<br />
_RxGroup 6 Group Message<br />
_RxAckBit 5 Acknowledge Message<br />
_RxExtMsgBit 4 Extended Message<br />
October 14, 2005 © 2005 Smarthome Technology
Address Register and Bits Description<br />
0x01B3 RxCmd1 Command byte 1<br />
0x01B4 RxCmd2 Command byte 2<br />
Developer’s <strong>Guide</strong> Page 98<br />
0x01B5 RxExtDataD Short message CRC or extended message Data D<br />
0x01B6 RxExtDataC Extended message Data C<br />
0x01B7 RxExtDataB Extended message Data B<br />
0x01B8 RxExtDataA Extended message Data A<br />
0x01B9 RxExtData9 Extended message Data 9<br />
0x01BA RxExtData8 Extended message Data 8<br />
0x01BB RxExtData7 Extended message Data 7<br />
0x01BC RxExtData6 Extended message Data 6<br />
0x01BD RxExtData5 Extended message Data 5<br />
0x01BE RxExtData4 Extended message Data 4<br />
0x01BF RxExtData3 Extended message Data 3<br />
0x01C0 RxExtData2 Extended message Data 2<br />
0x01C1 RxExtData1 Extended message Data 1<br />
0x01C2 RxExtData0 Extended message Data 0<br />
0x01C3 RxExtCrc Extended message CRC<br />
0x01C4 TxFrom0 Transmit “From” address high byte<br />
0x01C5 TxFrom1 Transmit “From” address middle byte<br />
0x01C6 TxFrom2 Transmit “From” address low byte<br />
0x01C7 TxTo0 Transmit “To” address high byte<br />
0x01C8 TxTo1 Transmit “To” address middle byte<br />
0x01C9 TxTo2 Transmit “To” address low byte<br />
0x01CA<br />
TxExtRpt Transmit Control Flags<br />
_TxBroadcastBit 7 Broadcast<br />
_TxGroup 6 Group<br />
_TxAckBit 5 Acknowledge<br />
_TxExtMsgBit 4 Extended<br />
0x01CB TxCmd1 Command byte 1<br />
0x01CC TxCmd2 Command byte 2<br />
0x01CD TxExtDataD Short message CRC or extended message Data D<br />
0x01CE TxExtDataC Extended message Data C<br />
October 14, 2005 © 2005 Smarthome Technology
Address Register and Bits Description<br />
0x01CF TxExtDataB Extended message Data B<br />
0x01D0 TxExtDataA Extended message Data A<br />
0x01D1 TxExtData9 Extended message Data 9<br />
0x01D2 TxExtData8 Extended message Data 8<br />
0x01D3 TxExtData7<br />
Extended message Data 7<br />
0x01D4 TxExtData6 Extended message Data 6<br />
0x01D5 TxExtData5 Extended message Data 5<br />
0x01D6 TxExtData4 Extended message Data 4<br />
0x01D7 TxExtData3 Extended message Data 3<br />
0x01D8 TxExtData2 Extended message Data 2<br />
0x01D9 TxExtData1 Extended message Data 1<br />
0x01DA TxExtData0 Extended message Data 0<br />
0x01DB TxExtCrc Extended message CRC<br />
0x01DD<br />
0x01E8 ⇒<br />
0x01EF<br />
Developer’s <strong>Guide</strong> Page 99<br />
RS_ERROR RS232 Error register<br />
_RX_Empty 7 Receive buffer empty<br />
_Rx_Full 6 Receive buffer full<br />
_RX_OF 5 Receive buffer overflow<br />
_RX_Busy 4 Receive busy<br />
_TX_Empty 3 Transmit buffer empty<br />
_TX_Full 2 Transmit buffer full<br />
_TX_OF 1 Transmit buffer overflow<br />
_TX_Busy 0 Transmit busy<br />
RX_Buffer RS232 receive buffer<br />
0x01DF RX_PTR Points to next open slot in serial receive buffer, if it contains<br />
0xE8, the buffer is empty<br />
0x0200 VALID = ‘P’ if EEPROM is valid; 0x0200 is beginning of microcontroller<br />
internal EEPROM<br />
0x0201 ID_H High byte if ID<br />
0x0202 ID_M Middle byte of ID<br />
0x0203 ID_L Low byte of ID<br />
0x0204 DEV_TYPE Device Type<br />
0x0205 SUB_TYPE Device Sub Type<br />
0x0206 REV Firmware Revision (MSN=Release, LSN=Ver)<br />
October 14, 2005 © 2005 Smarthome Technology
Address Register and Bits Description<br />
Developer’s <strong>Guide</strong> Page 100<br />
0x0207 MEM_SIZE Mask for installed external memory:<br />
0x0210 ⇒<br />
0x0211<br />
0x0212 ⇒<br />
0x0213<br />
0x0214 ⇒<br />
0x0215<br />
0x0216 ⇒<br />
0x0217<br />
00000000=none<br />
00001111=4K<br />
01111111=32K<br />
11111111=64K<br />
APP_ADDR_TEST Address of range of application for verification test<br />
APP_LEN_TEST Length of range of application for verification test<br />
APP_CHECK_TEST Two’s complement checksum of range of application for<br />
verification test<br />
APP_END Top of currently loaded SALad application. EEPROM is writeprotected<br />
from 0x0200 to the address contained here. Set<br />
0x16B bit 7 to enable over-writing.<br />
0x0230 TIMER_EVENT Entry point of SALad application for Timer Events<br />
0x0237 STATIC_EVENT Entry point of SALad application for Static Events<br />
0x0230 ⇒<br />
0x02FF<br />
0x0300 ⇒<br />
0x7FFF<br />
0x8000 ⇒<br />
0xFFFF<br />
SALad application code for fast execution; Microcontroller Internal EEPROM<br />
Slow SALad application code; External serial EEPROM<br />
If I2C_Addr bit 0 = 0, then 0x8000⇒0xFFFF is low region (0x0000⇒0x7FFF) of memory<br />
in I2C device specified by upper 7 bits of I2C_Addr.<br />
If I2C_Addr bit 0 = 1, then 0x8000⇒0xFFFF is high region (0x8000⇒0xFFFF) of memory<br />
in I2C device specified by upper 7 bits of I2C_Addr.<br />
October 14, 2005 © 2005 Smarthome Technology
IBIOS Events<br />
Developer’s <strong>Guide</strong> Page 101<br />
IBIOS events are all Static Events. If a SALad application is present, all of these<br />
Static Events are sent to a SALad event handler, like the one in the SALad coreApp<br />
Program, which comes pre-installed in The Smarthome PowerLinc Controller. In fact,<br />
some of these events, such as receiving <strong>INSTEON</strong> or X10 messages, require SALad<br />
handling in order to guarantee realtime processing. Timer Events also occur, but<br />
these must be handled by a SALad application, so they are documented elsewhere<br />
(see SALad Timers).<br />
Whenever an IBIOS Event occurs (assuming you have not disabled event reporting),<br />
IBIOS will notify your PC by sending an Event Report (0x45) IBIOS Serial Command.<br />
See the IBIOS Serial Command Summary Table for more information about event<br />
reporting.<br />
Eight events (0x0A through 0x11) can be prevented from occurring by clearing<br />
individual bits in the EventMask register at 0x016f (see Flat Memory Map).<br />
Initialization code sets EventMask to 0xFF at power up, so all events are enabled by<br />
default. Bit 7 (the MSb) of EventMask controls event 0x0A, down through bit 0 (the<br />
LSb), which corresponds to event 0x11.<br />
IBIOS Event Summary Table<br />
This table lists all currently defined Static Event handles.<br />
Handle<br />
Gives the number used by IBIOS to report the Event.<br />
Name<br />
Gives the name of the Event as used in software.<br />
Note<br />
See the item with the same number in IBIOS Event Details for more information.<br />
Description<br />
Briefly describes what happened to fire the event.<br />
SALad Static Events<br />
Handle Name Note Description<br />
0x00 EVNT_INIT 1 SALad initialization code started (automatic at power-up).<br />
0x01 EVNT_IRX_MYMSG 2 Received the first message in a hop sequence addressed to me.<br />
0x02 EVNT_IRX_MSG 2 Received the first message in a hop sequence not addressed to<br />
me.<br />
0x03 EVNT_IRX_PKT 2 Received a duplicate message in a hop sequence whether or not<br />
addressed to me (may occur after an 0x01 or 0x02 event).<br />
0x04 EVNT_ITX_ACK 2 Received expected Acknowledge message after Direct message<br />
sent.<br />
0x05 EVNT_ITX_NACK 2 Did not receive expected Acknowledge message after Direct<br />
message sent using 5 retries.<br />
0x06 EVNT_IRX_BADID 3 Received a message with an unknown To Address. The message<br />
was censored by replacing its contents with 0xFFs, except for<br />
October 14, 2005 © 2005 Smarthome Technology
Developer’s <strong>Guide</strong> Page 102<br />
SALad Static Events<br />
Handle Name Note Description<br />
the From Address and To Address LSBs).<br />
0x07 EVNT_IRX_ENROLL 4 Received an <strong>INSTEON</strong> message containing an enrollment-specific<br />
<strong>INSTEON</strong> command. The <strong>INSTEON</strong> message was received after<br />
a SALad Enroll instruction was executed while the SET Button<br />
was being held down, and before a four-minute timeout expired.<br />
The received message’s contents are in plaintext (i.e. not<br />
censored by masking with 0xFFs).<br />
0x08 EVNT_XRX_MSG 6 Received an X10 byte.<br />
0x09 EVNT_XRX_XMSG 6 Received an X10 Extended Message byte.<br />
0x0A EVNT_BTN_TAP 7 The SET Button was tapped for the first time.<br />
0x0B EVNT_BTN_HOLD 7 The SET Button is being held down.<br />
0x0C EVNT_BTN_REL 7 The SET Button is no longer being tapped or held down. The<br />
number of taps is in the TAP_CNT register at 0x0156.<br />
0x0D EVNT_TICK 8 Tick counter has expired (NTL_TICK)<br />
0x0E EVNT_ALARM 8 Hours and minutes equals current time<br />
0x0F EVNT_MIDNIGHT 8 Event occurs every midnight<br />
0x10 EVNT_2AM 8 Event occurs every 2:00 am<br />
0x11 EVNT_RX 9 Received a serial byte for SALad processing<br />
0x12 EVNT_SRX_COM 9 Received an unknown IBIOS Serial Command<br />
0x13 EVNT_DAUGHTER 10 Received interrupt from daughter card<br />
0x14 EVNT_LOAD_ON 11 Load turned on<br />
0x15 EVNT_LOAD_OFF 11 Load turned off<br />
IBIOS Event Details<br />
The numbers below refer to the Note column in the above IBIOS Event Summary<br />
Table.<br />
1. EVNT_INIT (0x00)<br />
When power is first applied, IBIOS runs its initialization code, then it checks for<br />
the existence of a valid SALad application program. If there is one, IBIOS fires<br />
this event and then starts SALad with this event in the event queue.<br />
You can force a power-on reset in software by setting bit 7 (_Reset) of the<br />
Control register at 0x0154 to one (see Flat Memory Map).<br />
2. EVNT_IRX_MYMSG (0x01), EVNT_IRX_MSG (0x02), EVNT_IRX_PKT<br />
(0x03)<br />
October 14, 2005 © 2005 Smarthome Technology
Developer’s <strong>Guide</strong> Page 103<br />
When IBIOS first receives a new <strong>INSTEON</strong> message that has not been seen<br />
before, the message may be arriving on its first hop, or it may be arriving on a<br />
subsequent hop, depending on the <strong>INSTEON</strong> environment. If the To Address of<br />
this new message matches the 3-byte IBIOS ID burned in at the factory, then the<br />
new message is to me, and an EVNT_IRX_MYMSG (0x01) event will fire. If<br />
the new message is not to me, then an EVNT_IRX_MSG (0x02) event will fire<br />
instead. If the new message was received before its last hop, then the same<br />
message may be received again on subsequent hops. Whenever this happens an<br />
EVNT_IRX_PKT (0x03) event will fire whether the duplicate message is to me<br />
or not to me.<br />
After any of these events fire, IBIOS will use a SALad application like the SALad<br />
coreApp Program to send an <strong>INSTEON</strong> Received (0x4F) IBIOS Serial Command<br />
(see IBIOS Serial Command Summary Table).<br />
3. EVNT_IRX_ACK (0x04), EVNT_IRX_NACK (0x05)<br />
After IBIOS sends a Direct (Point-to-Point) <strong>INSTEON</strong> message, it expects the<br />
addressee to respond with an <strong>INSTEON</strong> Acknowledge message. If IBIOS receives<br />
the Acknowledge message as expected, it fires an EVNT_IRX_ACK (0x04)<br />
event. On the other hand, if the expected Acknowledge message is not received,<br />
IBIOS will automatically retry sending the Direct message again. If after five<br />
retries the addressee still does not respond with an Acknowledgement message,<br />
IBIOS will fire an EVNT_IRX_NACK (0x05) event. One or the other (but not<br />
both) of these events is guaranteed to fire after sending a Direct message,<br />
although the EVNT_IRX_NACK (0x05) event may not fire for a long time due<br />
to the retries.<br />
After either of these events fires, IBIOS will use a SALad application like the<br />
SALad coreApp Program to send an <strong>INSTEON</strong> Received (0x4F) IBIOS Serial<br />
Command (see IBIOS Serial Command Summary Table).<br />
4. EVNT_IRX_BADID (0x06)<br />
If the To Address of an incoming <strong>INSTEON</strong> message does not match the 3-byte<br />
IBIOS ID burned in at the factory (i.e. the message is not to me), and the To<br />
Address does not match any of the IDs in IBIOS’s <strong>INSTEON</strong> Link Database, then<br />
for security reasons, the message is censored. A censored <strong>INSTEON</strong> message<br />
will have all of its data bytes replaced with 0xFFs, except for the low bytes of the<br />
From Address and the To Address. See Masking Non-linked Network Traffic for<br />
more information on <strong>INSTEON</strong> Security.<br />
After this event fires, IBIOS will use a SALad application like the SALad coreApp<br />
Program to send an <strong>INSTEON</strong> Received (0x4F) IBIOS Serial Command (see IBIOS<br />
Serial Command Summary Table).<br />
5. EVNT_IRX_ENROLL (0x07)<br />
This event supports <strong>INSTEON</strong> Device Linking, also known as enrollment, that is<br />
being handled by a suitable SALad application. The event may only fire after a<br />
SALad Enroll instruction (see SALad Instruction Summary) executes during the<br />
time that the SET Button is held down, and before a four-minute timer has<br />
expired. If during that time IBIOS sends or receives an <strong>INSTEON</strong> Broadcast<br />
message containing an <strong>INSTEON</strong> SET Button Pressed Slave (0x01) or SET Button<br />
October 14, 2005 © 2005 Smarthome Technology
Developer’s <strong>Guide</strong> Page 104<br />
Pressed Master (0x03) command or an <strong>INSTEON</strong> Direct message containing an<br />
<strong>INSTEON</strong> Assign to Group (0x01) or Delete from Group (0x02) command (see<br />
<strong>INSTEON</strong> Command Tables), the event will fire. The received message that<br />
triggered the event will not be censored by replacing its contents with 0xFFs, so<br />
that the SALad program can enroll the <strong>INSTEON</strong> device that sent the message in<br />
the <strong>INSTEON</strong> Link Database.<br />
Requiring that the SET Button be pushed enforces <strong>INSTEON</strong> Security by requiring<br />
Physical Possession of Devices.<br />
After this event fires, IBIOS will send an <strong>INSTEON</strong> Received (0x4F) IBIOS Serial<br />
Command (see IBIOS Serial Command Summary Table).<br />
6. EVNT_XRX_MSG (0x08), EVNT_XRX_XMSG (0x09)<br />
These events occur when IBIOS receives an X10 byte over the powerline. When<br />
IBIOS receives a new X10 byte, it fires an EVNT_XRX_MSG (0x08) event. If<br />
IBIOS determines that subsequent received X10 bytes are part of an Extended<br />
X10 message, then it will fire an EVNT_XRX_XMSG (0x09) event for those<br />
bytes. After IBIOS detects the end of the Extended X10 message (three 0x00<br />
bytes in succession), or else if a timeout expires, IBIOS will revert to firing an<br />
EVNT_XRX_MSG (0x08) event for the next X10 byte it receives.<br />
After either of these events occurs, IBIOS will use a SALad application like the<br />
SALad coreApp Program to send an X10 Received (0x4A) IBIOS Serial Command<br />
(see IBIOS Serial Command Summary Table).<br />
7. EVNT_BTN_TAP (0x0A), EVNT_BTN_HOLD (0x0B), EVNT_BTN_REL<br />
(0x0C)<br />
These events fire when the SET Button is pushed in various ways. A Button Tap<br />
occurs when the user pushes the SET Button and then lets up less than 350<br />
milliseconds (350 ms) later. A Button Hold occurs when the user pushes the SET<br />
Button and then lets up more than 350 ms later.<br />
The first time IBIOS detects a Button Tap, it fires an EVNT_BTN_TAP (0x0A)<br />
event. If there are more Button Taps following the first one, with less than 350<br />
ms between each one, then IBIOS does not fire an event, but it does count the<br />
number of Button Taps. When more than 350 ms elapses after a Button Tap,<br />
IBIOS fires an EVNT_BTN_REL (0x0C) event to indicate the SET Button has<br />
been released. At that time, you can inspect the TAP_CNT register at 0x0156<br />
(see Flat Memory Map) to see how many Button Taps occurred before the<br />
release.<br />
Whenever IBIOS detects a Button Hold it fires an EVNT_BTN_HOLD (0x0B)<br />
event, then when it detects that the button has been released it fires an<br />
EVNT_BTN_REL (0x0C) event.<br />
Note that a Button Hold can follow some number of Button Taps, in which case<br />
events EVNT_BTN_TAP (0x0A), EVNT_BTN_HOLD (0x0B), and<br />
EVNT_BTN_REL (0x0C) would occur in that order. Inspect TAP_CNT after the<br />
EVNT_BTN_REL (0x0C) event to see how many Button Taps there were.<br />
October 14, 2005 © 2005 Smarthome Technology
Developer’s <strong>Guide</strong> Page 105<br />
8. EVNT_TICK (0x0D), EVNT_ALARM (0x0E), EVNT_MIDNIGHT (0x0F),<br />
EVNT_2AM (0x10)<br />
These events depend on the IBIOS Software Realtime Clock (RTC), which counts<br />
powerline zero crossings (120 per second) for timing. The Software RTC must be<br />
set by a SALad program or by IBIOS Serial Commands upon power up for<br />
EVNT_ALARM (0x0E), EVNT_MIDNIGHT (0x0F), EVNT_2AM (0x10) to<br />
work properly.<br />
You can use EVNT_TICK (0x0D) to measure short time intervals, ranging from<br />
8.333 milliseconds (ms) up to 2.125 seconds. Each tick is one powerline zero<br />
crossing, which is 1/120 second, or 8.333 ms. To cause this event to fire, load a<br />
value from 1 to 255 into the NTL_TICK register at 0x0042 (see Flat Memory<br />
Map). After that number of ticks, IBIOS will fire this event one time only. You<br />
can disable this event at any time by loading 0x00 into NTL_TICK.<br />
Registers RTC _TIME_H and RTC _TIME_L at 0x0158 and 0x0159 contain a 16-bit<br />
value ranging from 0 to 1439 that counts the number of minutes that has elapsed<br />
since midnight. You can cause an EVNT_ALARM (0x0E) event to fire by loading<br />
a valid minutes-from-midnight value into the NTL_TIME_H and NTL _TIME_H<br />
registers at 0x0040 and 0x0041. When the value in RTC_TIME_H,L matches your<br />
value in NTL_TIME_H,L, IBIOS will fire EVNT_ALARM (0x0E). The value you<br />
loaded into NTL_TIME_H,L is not altered when the event fires, so the event will<br />
fire every day. However, if you load an invalid value (greater than 1439) into<br />
NTL_TIME_H,L, then the event will never fire.<br />
The EVNT_MIDNIGHT (0x0F) and EVNT_2AM (0x10) events fire at midnight<br />
and at 2:00 am, as you would expect.<br />
9. EVNT_RX (0x11), EVNT_SRX_COM (0x12)<br />
These events allow the number of IBIOS Serial Commands to be extended. All<br />
IBIOS Serial Commands begin with 0x02, followed by the number of the<br />
command. If IBIOS receives a Serial Command number outside the range 0x40<br />
through 0x48 (see IBIOS Serial Command Summary Table), it will fire the<br />
EVNT_SRX_COM (0x12) event, then start a two-second timer. Thereafter,<br />
every time IBIOS receives a serial byte, it will fire the EVNT_RX_COM (0x11)<br />
event and restart the two-second timer. If the two-second timer expires, IBIOS<br />
will send a serial NAK (ASCII 0x15) and stop firing EVNT_RX_COM (0x11)<br />
events.<br />
When you are finished parsing the incoming IBIOS Serial Command, clear the<br />
two-second timer yourself by clearing bits 5 and 6, _RSComLimit1 and<br />
_RSComLimit, in the RS_CONTROL register at 0x016B (see Flat Memory Map).<br />
If you want more time, you can get another two seconds by setting the same two<br />
bits to one.<br />
10. EVNT_DAUGHTER (0x13)<br />
IBIOS fires this event when it detects that port pin RB6 on the microprocessor<br />
went low. Normally this is caused by an attached daughter card requesting an<br />
interrupt.<br />
October 14, 2005 © 2005 Smarthome Technology
Developer’s <strong>Guide</strong> Page 106<br />
11. EVNT_LOAD_ON (0x14), EVNT_LOAD_OFF (0x15)<br />
These events are for monitoring electrical loads connected to the <strong>INSTEON</strong><br />
device. They will fire in response to the state of current-sensing hardware, and<br />
so are implementation-specific. Contact the <strong>INSTEON</strong> Developer’s Forum or<br />
email sdk@insteon.net for more information.<br />
October 14, 2005 © 2005 Smarthome Technology
Developer’s <strong>Guide</strong> Page 107<br />
IBIOS Serial Communication Protocol and<br />
Settings<br />
In This Section<br />
IBIOS Serial Communication Protocol<br />
Gives the protocol for communicating serially with the PLC.<br />
IBIOS RS232 Port Settings<br />
Shows how to set up your PC’s COM (RS232) port to talk to an RS232 PLC.<br />
IBIOS USB Serial Interface<br />
Describes how to use your PC’s USB port to talk to a USB PLC.<br />
October 14, 2005 © 2005 Smarthome Technology
Developer’s <strong>Guide</strong> Page 108<br />
IBIOS Serial Communication Protocol<br />
All IBIOS Serial Commands start with ASCII 0x02 (STX, Start-of-Text) followed by<br />
the Serial Command number (see IBIOS Serial Commands). What data follows the<br />
command depends on the command syntax (see IBIOS Serial Command Summary<br />
Table).<br />
IBIOS will respond with an echo of the command number followed by any data that<br />
the command returns.<br />
If IBIOS is responding to a Serial Command that it received, it will terminate its<br />
response with ASCII 0x06 (ACK, Acknowledge), or sometimes ASCII 0x15 (NAK,<br />
Negative Acknowledge).<br />
(S: and R: denote serial data you Send to or Receive from IBIOS, respectively.)<br />
S: 0x02 <br />
R: 0x02 0x06<br />
If IBIOS is not ready, it will return ASCII 0x15 (NAK).<br />
S: 0x02 <br />
R: 0x15 (NAK)<br />
If you receive 0x15 (NAK), resend your Serial Command.<br />
IBIOS RS232 Port Settings<br />
To communicate to an RS232 PLC, set your PC’s COM port as follows:<br />
Setting Value<br />
Baud 4800<br />
Data Bits 8<br />
Parity N<br />
Stop Bits 1<br />
Hardware Flow Control None<br />
Software Flow Control None<br />
October 14, 2005 © 2005 Smarthome Technology
IBIOS USB Serial Interface<br />
Developer’s <strong>Guide</strong> Page 109<br />
The interface to a USB PLC is a simple USB wrapper around the IBIOS Serial<br />
Communication Protocol, implemented using the Human Interface Device (HID)<br />
interface. See, for example, http://www.lvr.com/hidpage.htm for more information<br />
on using HID to implement a USB interface.<br />
Smarthome’s VendorID and ProductID are listed at http://www.linuxusb.org/usb.ids.<br />
The ProductID for the USB PowerLinc V2 Controller is 0x0004.<br />
When communicating to a USB PLC, send the same commands as given in IBIOS<br />
Serial Commands, except use 8-byte USB packets.<br />
The PLC will set the most significant bit of the Count byte to indicate Clear-to-Send,<br />
i.e. that the PLC is ready to receive more data.<br />
For example, to send the IBIOS Serial Command 0x48 (Get PLC Version), send the<br />
following 8-byte packet (data bytes are bold):<br />
HID USB 8-byte Packet<br />
Count Data<br />
0x02 0x02 0x48 0x00 0x00 0x00 0x00 0x00<br />
The PLC will reply with data similar to the following (data bytes are bold; 0x80 in the<br />
count indicates that the PLC is ready to receive more data):<br />
HID USB 8-byte Packet<br />
Count Data<br />
0x80 0x00 0x00 0x00 0x00 0x00 0x00 0x00<br />
0x01 0x02 0x00 0x00 0x00 0x00 0x00 0x00<br />
0x03 0x48 0xff 0xff 0x00 0x00 0x00 0x00<br />
0x03 0xff 0x04 0x00 0x00 0x00 0x00 0x00<br />
0x02 0x23 0x06 0x00 0x00 0x00 0x00 0x00<br />
October 14, 2005 © 2005 Smarthome Technology
IBIOS Serial Commands<br />
Developer’s <strong>Guide</strong> Page 110<br />
The IBIOS Serial Command set is the basic interface between a computing device<br />
such as a PC or dedicated home controller and a serially connected <strong>INSTEON</strong> Bridge<br />
device such as The Smarthome PowerLinc Controller (PLC). For example, a PC<br />
connected to a PLC could use IBIOS Serial Commands to send and receive <strong>INSTEON</strong><br />
or X10 messages directly, or it could download and debug a SALad program that<br />
runs on the PLC.<br />
IBIOS Serial Commands also allow indirect access, via <strong>INSTEON</strong> messages, to other<br />
<strong>INSTEON</strong> devices on the network. For instance, you could upgrade the capabilities of<br />
SALad-enabled <strong>INSTEON</strong> devices by remotely installing and debugging new SALad<br />
applications in them.<br />
Some of the IBIOS Serial Commands require a SALad application such as the<br />
coreApp Program to be running in order to ensure realtime execution.<br />
In This Section<br />
IBIOS Serial Command Table<br />
Describes all of the IBIOS Serial Commands in an IBIOS Serial Command<br />
Summary Table and gives IBIOS Serial Command Details.<br />
IBIOS Serial Command Examples<br />
Gives examples of how to use the IBIOS Serial Commands.<br />
SALad<br />
October 14, 2005 © 2005 Smarthome Technology
IBIOS Serial Command Table<br />
IBIOS Serial Command Parameters<br />
Developer’s <strong>Guide</strong> Page 111<br />
This is what the common parameters shown in the Format column of the IBIOS<br />
Serial Command Summary Table mean. Parameters not listed here should be<br />
understood from the context.<br />
MSB means Most-Significant Byte, LSB means Least-Significant Byte, MSb means<br />
Most-Significant bit.<br />
Parameter Description<br />
Address High (Low) MSB (LSB) of a 16-bit address<br />
Length High (Low) MSB (LSB) of a 16-bit length of a data block<br />
Checksum High (Low) MSB (LSB) of a 16-bit value calculated by summing all the bytes in a<br />
data block specified in an IBIOS Serial Command, then taking the two’s<br />
complement<br />
Data Block of data bytes<br />
Event Handle 8-bit number indicating the event that fired (see IBIOS Events)<br />
Timer Value 8-bit time value:<br />
1 to 127 seconds, if the MSb (bit 7) is 0 (clear)<br />
1 to 127 minutes, if the MSb (bit 7) is 1 (set)<br />
October 14, 2005 © 2005 Smarthome Technology
IBIOS Serial Command Summary Table<br />
Developer’s <strong>Guide</strong> Page 112<br />
This table lists all of the IBIOS Serial Commands supported by the PLC.<br />
Code<br />
Gives the hexadecimal number of the IBIOS Serial Command. SALad means<br />
that the command is only applicable if a suitable SALad application, such as the<br />
SALad coreApp Program, is running.<br />
Command<br />
Gives the name of the IBIOS Serial Command.<br />
Note<br />
See the item with the same number in IBIOS Serial Command Details for more<br />
information.<br />
Format<br />
Gives the syntax of the IBIOS Serial Command, including any parameters.<br />
S: and R: denote serial data you Send to or Receive from IBIOS, respectively. See<br />
IBIOS Serial Communication Protocol for more information.<br />
All IBIOS Serial Commands start with ASCII 0x02 (STX, Start-of-Text) followed by<br />
the Serial Command number. See IBIOS Serial Command Parameters, above, for<br />
the meaning of the command parameters.<br />
All fields in this table contain only one byte, except for those with ‘…’ (e.g. ,<br />
or ), which contain a variable number of bytes.<br />
Code Command Note Format<br />
0x40<br />
0x41<br />
SALad<br />
0x42<br />
0x43<br />
SALad<br />
Download 1<br />
(IBIOS<br />
receives data<br />
from you)<br />
Fixed-length<br />
Message<br />
Upload<br />
(IBIOS sends<br />
data to you)<br />
Variablelength<br />
Text<br />
Message<br />
0x44 Get<br />
Checksum<br />
2<br />
1<br />
2<br />
3<br />
IBIOS Serial Commands<br />
S: 0x02 0x40 <br />
R: 0x02 0x40 <br />
R: 0x02 0x41 <br />
NOTE: can contain unrestricted data, such as embedded<br />
<strong>INSTEON</strong> or X10 messages.<br />
S: 0x02 0x42 <br />
R: 0x02 0x42 0x06<br />
R: 0x02 0x43 0x03 (ASCII ETX, End-of-Text)<br />
NOTE: must not contain 0x03 (ETX, End-of-Text).<br />
S: 0x02 0x44 <br />
R: 0x02 0x44 0x06<br />
0x45 Event Report 4 R: 0x02 0x45 can be disabled<br />
October 14, 2005 © 2005 Smarthome Technology
Code Command Note Format<br />
Developer’s <strong>Guide</strong> Page 113<br />
IBIOS Serial Commands<br />
0x46 Mask 5 S: 0x02 0x46 <br />
0x47 Simulated<br />
Event<br />
0x48 Get Version 7 S: 0x02 0x48<br />
0x49<br />
SALad<br />
0x4A<br />
SALad<br />
0x4F<br />
SALad<br />
Debug<br />
Report<br />
X10 Byte<br />
Received<br />
<strong>INSTEON</strong><br />
Message<br />
Received<br />
6<br />
8<br />
9<br />
10<br />
IBIOS Serial Command Details<br />
R: 0x02 0x46 0x06<br />
S: 0x02 0x47 <br />
R: 0x02 0x47 0x06<br />
R: 0x02 0x48 <br />
<br />
0x06<br />
R: 0x02 0x49 <br />
R: 0x02 0x4A <br />
R: 0x02 0x4F <br />
The numbers below refer to the Note column in the above IBIOS Serial Command<br />
Summary Table.<br />
1. Download (0x40), Upload (0x42)<br />
Use these commands to write Download (0x40) or read Upload (0x42)<br />
IBIOS’s memory. The Flat Memory Map lists all of the memory locations that you<br />
can access, and defines what the contents are.<br />
You can neither read nor write the firmware in IBIOS’s EPROM. The<br />
microprocessor’s program counter (appearing at locations 0x0002, 0x0082,<br />
0x0102, and 0x0182) is write-protected, as is the Enrollment Timer at 0x016D.<br />
No harm will occur if you attempt to read or write address locations where there<br />
is no memory, but the results will be indeterminate.<br />
See item 3, Get Checksum (0x44), for IBIOS’s method of calculating<br />
checksums (two’s complement of a 16-bit sum).<br />
After downloading, even if you receive 0x06 (ACK), you should immediately issue<br />
a Get Checksum (0x44) Serial Command to verify that IBIOS wrote the data to<br />
memory correctly.<br />
If you are setting or clearing individual flag bits in a register, use the Mask<br />
(0x46) command to avoid affecting flags you are not changing.<br />
October 14, 2005 © 2005 Smarthome Technology
Developer’s <strong>Guide</strong> Page 114<br />
2. Fixed-length Message (0x41), Variable-length Text Message (0x43)<br />
These Serial Commands require a SALad application such as the SALad coreApp<br />
Program to be running. A SALad program can send up to 255 bytes of<br />
unrestricted (ASCII or binary) data to the host using a Fixed-length Message<br />
(0x41) Serial Command containing a length byte.<br />
To send simple text messages without a length restriction, a SALad program can<br />
use the Variable-length Text Message (0x43) Serial Command. This<br />
command does not use a length byte. Instead, it uses an ASCII 0x03 (ETX, Endof-Text)<br />
byte to delimit the end of the ASCII text message, so the text message<br />
must not contain an embedded ETX character before the actual end of the<br />
message.<br />
3. Get Checksum (0x44)<br />
IBIOS calculates checksums by summing up all of the bytes in the given range<br />
into a 16-bit register, then taking a two’s complement of the 16-bit sum. You<br />
can take a two’s complement by inverting all 16 bits and then incrementing by<br />
one, or else you can just subtract the 16-bit value from 0x0000.<br />
4. Event Report (0x45)<br />
IBIOS sends this Serial Command whenever one of the IBIOS Events given in the<br />
IBIOS Event Summary Table fires.<br />
You can prevent IBIOS from sending Event Reports by setting bit 1,<br />
_NoEventRpt, in the Control register at 0x0154 to one (see Flat Memory Map).<br />
IBIOS clears this flag to zero at power up, so Event Reports are enabled by<br />
default.<br />
5. Mask (0x46)<br />
Use this Serial Command to set or clear individual flag bits in a register without<br />
affecting flags you are not changing.<br />
To set one or more bits in a register to one, set the corresponding bits in the OR<br />
Mask to one. Bits set to zero in the OR Mask will not change the corresponding<br />
bits in the register.<br />
To clear one or more bits in a register to zero, set the corresponding bits in the<br />
AND Mask to zero. Bits set to one in the AND Mask will not change the<br />
corresponding bits in the register.<br />
6. Simulated Event (0x47)<br />
You can force IBIOS to fire one of the Static Events in the IBIOS Event Summary<br />
Table with this Serial Command by sending the desired number<br />
with a of zero. You cannot use this Serial Command to fire an<br />
EVNT_INIT (0x00) initialization event, but there is an alternate method to<br />
force a power-on reset (see IBIOS Event Details, Note 1).<br />
IBIOS will fire Timer Events, but unless you are running a SALad program with<br />
Timer Event handling code, nothing will happen. See SALad Timers for an<br />
explanation of SALad Timer events. To simulate a Timer Event, set
Developer’s <strong>Guide</strong> Page 115<br />
Handle> to the Timer Index number of the SALad handler for the timer, and set<br />
to a non-zero value denoting how much time should elapse<br />
before the Timer Event fires. If the high bit of is 0, then the time<br />
will be 1 to 127 seconds; if the high bit is 1, then the time will be 1 to 127<br />
minutes.<br />
7. Get Version (0x48)<br />
This Serial Command retrieves the 3-byte <strong>INSTEON</strong> ID number (see Device<br />
Addresses), 2-byte Device Type, and 1-byte Firmware Revision burned in at the<br />
factory. This information is read-only.<br />
8. Debug Report (0x49)<br />
You can remotely debug a SALad program with this Serial Command. This is the<br />
underlying mechanism used by the IDE debugger described in the SALad<br />
Integrated Development Environment User’s <strong>Guide</strong>.<br />
See the IBIOS Remote Debugging section for details on how IBIOS remote<br />
debugging works. When remote debugging is enabled, IBIOS will use this Serial<br />
Command to report the location of the next SALad instruction to be executed.<br />
9. X10 Byte Received (0x4A)<br />
This Serial Command requires a SALad application such as the SALad coreApp<br />
Program to be running. After IBIOS fires an EVNT_XRX_MSG (0x08) or<br />
EVNT_XRX_XMSG (0x09) (see IBIOS Event Details), The SALad app will report<br />
the received X10 byte by sending this Serial Command.<br />
The byte following the 0x4A command number tells whether the received X10<br />
byte is an X10 Address (the byte is 0x00) or X10 Command (the byte is 0x01).<br />
If you are receiving an X10 Extended Message, then this byte is irrelevant.<br />
See IBIOS X10 Signaling for more information.<br />
10. <strong>INSTEON</strong> Message Received (0x4F)<br />
This Serial Command requires a SALad application such as the SALad coreApp<br />
Program to be running. After IBIOS fires any of the events 0x01 through 0x07<br />
(see IBIOS Event Details), The SALad app will report the <strong>INSTEON</strong> message<br />
received by sending this Serial Command.<br />
To determine if the <strong>INSTEON</strong> message’s length is 9 bytes (Standard) or 23 bytes<br />
(Extended), inspect the message’s Extended Message Flag.<br />
October 14, 2005 © 2005 Smarthome Technology
IBIOS Serial Command Examples<br />
Developer’s <strong>Guide</strong> Page 116<br />
This section contains examples showing how to use various IBIOS Serial Commands<br />
described in the IBIOS Serial Command Table above. The examples assume you are<br />
serially connected to The Smarthome PowerLinc Controller (PLC) running the default<br />
SALad coreApp Program.<br />
In This Section<br />
Get Version<br />
Get the <strong>INSTEON</strong> Address, Device Type, and Firmware Revision of the PLC.<br />
Read and Write Memory<br />
Read and write memory in the PLC based on the flat memory map.<br />
Get Checksum on Region of Memory<br />
Get the checksum over a region of PLC memory based on the flat memory map.<br />
Send <strong>INSTEON</strong><br />
Send an <strong>INSTEON</strong> command.<br />
Receive <strong>INSTEON</strong><br />
Receive an <strong>INSTEON</strong> command.<br />
Send X10<br />
Send an X10 command.<br />
Simulated Event<br />
Fire an IBIOS Event and start the SALad Engine with the event.<br />
October 14, 2005 © 2005 Smarthome Technology
Get Version<br />
Summary<br />
Developer’s <strong>Guide</strong> Page 117<br />
In this example we will use the Get Version (0x48) IBIOS Serial Command to get<br />
the PLC’s 3-byte <strong>INSTEON</strong> ID number (see Device Addresses), 2-byte Device Type,<br />
and 1-byte Firmware Revision burned in at the factory.<br />
Procedure<br />
1. Send the Get Version (0x48) IBIOS Serial Command from the<br />
Command Summary Table:<br />
0x02 0x48.<br />
2. The response should be:<br />
IBIOS Serial<br />
0x02 0x48 <br />
0x06.<br />
October 14, 2005 © 2005 Smarthome Technology
Read and Write Memory<br />
Summary<br />
Developer’s <strong>Guide</strong> Page 118<br />
In this example we will use the Upload (0x42) and Download (0x40) IBIOS Serial<br />
Commands to alter data stored in the PLC’s serial EEPROM chip. See the Flat<br />
Memory Map for memory address locations. First we will read 4 bytes of data<br />
starting at the beginning of external EEPROM at address 0x0300, then we will write<br />
0x55 0xAA 0x55 0xAA to those locations, then read the data back out to observe<br />
our changes.<br />
Procedure<br />
1. Use the Upload (0x42) IBIOS Serial Command from the IBIOS Serial Command<br />
Summary Table to read 0x0004 bytes starting at 0x0300:<br />
0x02 0x42 0x03 0x00 0x00 0x04.<br />
You can check the response to see what the four bytes are. See the IBIOS Serial<br />
Command Summary Table for the response syntax.<br />
2. Now use Download (0x40) to write 0x55 0xAA 0x55 0xAA into those<br />
locations:<br />
0x02 0x40 0x03 0x00 0x00 0x04 0xFD 0xFB 0x55 0xAA 0x55 0xAA.<br />
It is not mandatory that you include a valid checksum (here 0xFDFB), but it is<br />
strongly recommended, because you can then use a Get Checksum (0x44)<br />
IBIOS Serial Command to be sure the data was properly written, without having<br />
to read all of the data back.<br />
The response should be:<br />
0x02 0x40 0x03 0x00 0x00 0x04 0x06.<br />
Note that the response merely echoes the first 6 bytes of the received command,<br />
followed by an ASCII 0x06 (ACK) indicating that the command was properly<br />
received. The ACK does not indicate that the command executed properly.<br />
3. Now read out the four bytes at 0x0300 again as in Step 1:<br />
0x02 0x42 0x03 0x00 0x00 0x04.<br />
Check that the response contains the 0x55 0xAA 0x55 0xAA data. For further<br />
validation, you can also verify that the checksum in the response matches a<br />
checksum that you compute over the received data.<br />
October 14, 2005 © 2005 Smarthome Technology
Developer’s <strong>Guide</strong> Page 119<br />
Get Checksum on Region of Memory<br />
Summary<br />
This example will demonstrate getting the checksum over the first 10 bytes of SALad<br />
application code. The checksum is computed as the two’s complement of a 16-bit<br />
sum of the bytes. You can take a two’s complement by inverting all 16 bits in the<br />
sum and then incrementing by one, or else you can just subtract the 16-bit value<br />
from 0x0000.<br />
For this example the beginning of the SALad application starts at 0x0230 and is 0x0a<br />
bytes long.<br />
Procedure<br />
1. Use the Get Checksum (0x44) IBIOS Serial Command from the IBIOS Serial<br />
Command Summary Table to get the checksum on the region starting at 0x0230<br />
and extending 0x000a bytes:<br />
0x02 0x44 0x02 0x30 0x00 0xa0.<br />
2. Retrieve the checksum from the return message, which should be:<br />
0x02 0x44 0x02 0x30 0x00 0xA0 0x06.<br />
October 14, 2005 © 2005 Smarthome Technology
Send <strong>INSTEON</strong><br />
Summary<br />
Developer’s <strong>Guide</strong> Page 120<br />
Before sending <strong>INSTEON</strong> messages you should familiarize yourself with <strong>INSTEON</strong><br />
Messages and <strong>INSTEON</strong> Commands.<br />
In this example we will send the <strong>INSTEON</strong> ON command with Level 0xFF (full on)<br />
from a PLC to a LampLinc V2 Dimmer that has an <strong>INSTEON</strong> Address of 0x0002AC.<br />
We will first copy the <strong>INSTEON</strong> message to an area of PLC memory used as a<br />
message construction buffer. Then we will set the Request-to-Send <strong>INSTEON</strong> flag,<br />
causing the PLC to send the <strong>INSTEON</strong> message in its construction buffer to the<br />
LampLinc.<br />
Note that for security reasons, IBIOS will always insert its own address (the 3-byte<br />
IBIOS ID burned in at the factory) in the From Address field no matter what you<br />
write to the construction buffer. See Masking Non-linked Network Traffic for more<br />
information on <strong>INSTEON</strong> Security. Therefore, we do not need to put the From<br />
Address in the <strong>INSTEON</strong> message.<br />
Procedure<br />
1. Use the Download (0x40) IBIOS Serial Command from the IBIOS Serial<br />
Command Summary Table to load this 6-byte <strong>INSTEON</strong> message starting with<br />
the To Address field<br />
0x00 0x02 0xAC 0x0F 0x11 0xFF<br />
into the PLC’s Construction Buffer starting at the To Address field at location<br />
0x1A4 (see Flat Memory Map).<br />
The fully formed Download (0x40) IBIOS Serial Command, with the embedded<br />
<strong>INSTEON</strong> message in bold, is:<br />
0x02 0x40 0x01 0xA4 0x00 0x06 0xFD 0x88 0x00 0x02 0xAC 0x0F 0x11<br />
0xFF.<br />
The returned serial message should be an echo of the first 6 bytes of the Serial<br />
Command followed by an ASCII 0x06 (ACK), like this:<br />
0x02 0x40 0x01 0xA4 0x00 0x06 0x06.<br />
2. Now use the Mask (0x46) IBIOS Serial Command to set the _I_Transmit<br />
Request-to-Send <strong>INSTEON</strong> flag (bit 4) in the I_Control register at 0x142 (see<br />
Flat Memory Map), by sending:<br />
0x02 0x46 0x01 0x42 0x10 0xFF.<br />
The returned serial message should be:<br />
0x02 0x46 0x01 0x42 0x10 0xFF 0x06.<br />
October 14, 2005 © 2005 Smarthome Technology
Receive <strong>INSTEON</strong><br />
Summary<br />
Developer’s <strong>Guide</strong> Page 121<br />
Before receiving <strong>INSTEON</strong> messages you should familiarize yourself with <strong>INSTEON</strong><br />
Messages and <strong>INSTEON</strong> Commands.<br />
Here we assume you are using a The Smarthome PowerLinc Controller (PLC) running<br />
the default SALad coreApp Program.<br />
When the PLC receives an <strong>INSTEON</strong> message, IBIOS fires an IBIOS Event that a<br />
SALad program handles. PLCs come from the factory with an open-source SALad<br />
coreApp Program installed, and you can create your own custom applications by<br />
modifying coreApp.<br />
When an <strong>INSTEON</strong> message arrives, coreApp’s event handlers send an <strong>INSTEON</strong><br />
Received (0x4F) IBIOS Serial Command containing the IBIOS Event number and<br />
the <strong>INSTEON</strong> message to your PC. Your PC can then deal with the <strong>INSTEON</strong><br />
Received (0x4F) IBIOS Serial Command whenever it shows up in its serial buffer.<br />
Procedure<br />
1. When an <strong>INSTEON</strong> message is received, coreApp (and all applications built upon<br />
it) will send the message data to your PC using the following format:<br />
0x02 0x4F <br />
2. The Event Handle byte tells which of the IBIOS Events (0x01 through 0x07)<br />
IBIOS fired to trigger the SALad coreApp program. See the IBIOS Event<br />
Summary Table and IBIOS Event Details for more information about what kinds<br />
of <strong>INSTEON</strong> message fire which events.<br />
3. To determine if the length of the <strong>INSTEON</strong> message is 9 bytes (Standard) or 23<br />
bytes (Extended), inspect the message’s Extended Message Flag (bit 4 of the<br />
message’s 7 th byte). The <strong>INSTEON</strong> Message Summary Table shows all possible<br />
<strong>INSTEON</strong> message types.<br />
4. To determine the meaning of the <strong>INSTEON</strong> message, look at the <strong>INSTEON</strong><br />
Command 1 and 2 fields in the message. The <strong>INSTEON</strong> Command Tables<br />
enumerate all of the possible <strong>INSTEON</strong> Commands.<br />
October 14, 2005 © 2005 Smarthome Technology
Send X10<br />
Summary<br />
Developer’s <strong>Guide</strong> Page 122<br />
In this example we will send X10 A1/AON over the powerline using a PLC and IBIOS<br />
Serial Commands. First we will download the A1 X10 address into the X10 transmit<br />
buffer. Then we will set the Request-to-Send X10 bit and clear the<br />
Command/Address bit of the X10 Flags register with a Mask (0x46) IBIOS Serial<br />
Command. Then we will download the AON X10 command into the X10 transmit<br />
buffer, followed by setting both the Request-to-Send X10 and the Command/Address<br />
bits with another Mask (0x46) command.<br />
See IBIOS X10 Signaling for more information.<br />
Procedure<br />
1. Use the Download (0x40) IBIOS Serial Command from the IBIOS Serial<br />
Command Summary Table to load an X10 A1 address (0x66) into the X10<br />
transmit buffer X10_TX at 0x0165 (see Flat Memory Map) by sending:<br />
0x02 0x40 0x01 0x65 0x00 0x01 0xFF 0x33 0x66,<br />
then check for the ASCII 0x06 (ACK) at the end of the echoed response:<br />
0x02 0x40 0x01 0x65 0x00 0x01 0x06.<br />
2. Use the Mask (0x46) IBIOS Serial Command to set the _X10_RTS flag (bit 7)<br />
and clear the _X10_TXCOMMAND flag (bit 3) in the X10_FLAGS register at<br />
0x0166 (see Flat Memory Map) via:<br />
0x02 0x46 0x01 0x66 0x80 0xF7,<br />
then check for the ASCII 0x06 (ACK) at the end of the echoed response:<br />
0x02 0x46 0x01 0x66 0x80 0xF7 0x06.<br />
3. The PLC will now send an A1 X10 address over the powerline.<br />
4. As in Step 1, load an X10 AON command (0x62) into the X10 transmit buffer by<br />
sending:<br />
0x02 0x40 0x01 0x65 0x00 0x01 0xff 0x37 0x62,<br />
and check for an appropriate response:<br />
0x02 0x40 0x01 0x65 0x00 0x01 0x06.<br />
5. As in Step 2, use the Mask command to set the _X10_RTS bit and set the<br />
_X10_TXCOMMAND bit via:<br />
0x02 0x46 0x01 0x66 0x88 0xff<br />
then check for an appropriate response:<br />
0x02 0x46 0x01 0x66 0x88 0xFF 0x06.<br />
October 14, 2005 © 2005 Smarthome Technology
Developer’s <strong>Guide</strong> Page 123<br />
6. The PLC will now send an AON X10 command over the powerline.<br />
October 14, 2005 © 2005 Smarthome Technology
Simulated Event<br />
Summary<br />
Developer’s <strong>Guide</strong> Page 124<br />
You can use the Simulated Event (0x47) IBIOS Serial Command from the IBIOS<br />
Serial Command Summary Table to cause the PLC to run its SALad application with<br />
the specified event or timer handle in the event queue. See SALad Event Handling<br />
for more information on the event processing system that SALad programs use.<br />
This example lists a demo SALad application that you can install in the PLC using the<br />
tools documented in the SALad Integrated Development Environment User’s <strong>Guide</strong>.<br />
Whenever when the PLC’s SET Button is tapped, the EVNT_BTN_TAP (0x0A)<br />
IBIOS Event fires (see IBIOS Event Summary Table). The demo application’s event<br />
handler uses a Variable-length Text Message (0x43) IBIOS Serial Command to<br />
send a ‘Button tap detected’ ASCII message over the serial connection when this<br />
event fires.<br />
You can use this same method for testing other event processing code in your SALad<br />
applications.<br />
To demonstrate the Simulated Event (0x47) IBIOS Serial Command we will send a<br />
simulated EVNT_BTN_TAP (0x0A) and observe the ‘Button tap detected’ message.<br />
Procedure<br />
1. Using the SALad IDE, download the following SALad application into the<br />
PowerLinc V2 Controller (iPLC_Map.sal has the definitions and equates for the<br />
Flat Memory Map, and Event.sal has equates for the IBIOS Events):<br />
INCLUDE "iPLC_Map.sal"<br />
INCLUDE "Event.sal"<br />
; API Macro Definitions<br />
DEFINE API DATA 0x04<br />
DEFINE SendString API 0x86 ; send a null terminated string<br />
DEFINE SendByte API 0x44<br />
; application header<br />
ORG 0x210<br />
DATA 0x02 0x10 ; start at 0x0210<br />
DATA 0x00 0x01 ; length 1<br />
DATA 0x00 0x00 ; checksum 0 (no verification)<br />
; entry point for timers<br />
ORG 0x230<br />
END ; just exit if timer<br />
; entry point for static events<br />
ORG 0x237<br />
COMP= #EVNT_INIT, NTL_EVENT, ButtonEvent ; if initialization<br />
MOVE$ #0x00, NTL_TIMERS, 0x2D ; clear out NTL_TIMERS<br />
ButtonEvent<br />
COMP= #EVNT_BTN_TAP, NTL_EVENT, Exit ; check for button tap<br />
SendString strButtonMessage<br />
Exit<br />
END<br />
strButtonMessage<br />
DATA "Button tap detected", 0x0d, 0x0a, 0x00<br />
2. Tap the SET Button on the PLC and you should see the message ‘Button tap<br />
detected’ displayed in the IDE’s Comm Window – ASCII Window.<br />
3. Now send the Simulated Event serial command from the IBIOS Serial<br />
Command Summary Table to fire the EVNT_BTN_TAP (0x0A) IBIOS Event:<br />
October 14, 2005 © 2005 Smarthome Technology
0x02 0x47 0x0A 0x00.<br />
Developer’s <strong>Guide</strong> Page 125<br />
You should see the same ‘Button tap detected’ message displayed in the IDE’s<br />
ASCII Window.<br />
October 14, 2005 © 2005 Smarthome Technology
IBIOS <strong>INSTEON</strong> Engine<br />
Developer’s <strong>Guide</strong> Page 126<br />
The IBIOS <strong>INSTEON</strong> Engine handles <strong>INSTEON</strong> message transport. The format and<br />
meaning of <strong>INSTEON</strong> messages are described in detail in the section <strong>INSTEON</strong><br />
Messages. How <strong>INSTEON</strong> messages propagate in an <strong>INSTEON</strong> network is explained<br />
in the section <strong>INSTEON</strong> Signaling Details.<br />
You can use the method given in the Send <strong>INSTEON</strong> example in the IBIOS Serial<br />
Commands section to send an <strong>INSTEON</strong> message with the <strong>INSTEON</strong> Engine.<br />
However, receiving <strong>INSTEON</strong> messages is time-critical, and although it is technically<br />
possible to wait for one of the ‘<strong>INSTEON</strong> message received’ events and then poll the<br />
<strong>INSTEON</strong> receive buffer, the buffer can easily be overwritten by new <strong>INSTEON</strong><br />
messages if it is not read quickly enough. Therefore, the safest way to receive<br />
<strong>INSTEON</strong> messages is to use the SALad coreApp Program pre-installed in The<br />
Smarthome PowerLinc Controller, or else to write your own SALad application that<br />
employs the same method as coreApp. See the Receive <strong>INSTEON</strong> example in the<br />
IBIOS Serial Commands section for more details.<br />
The <strong>INSTEON</strong> Engine automatically handles <strong>INSTEON</strong> Message Hopping and<br />
<strong>INSTEON</strong> Message Retrying. It also deals with the Message Integrity Byte so you<br />
don’t have to. Whenever you send or receive a Direct (Point-to-Point) <strong>INSTEON</strong><br />
message, the <strong>INSTEON</strong> Engine knows about the expected Acknowledgement<br />
message and handles it for you, then fires one of the EVNT_ITX_ACK or<br />
EVNT_ITX_NACK IBIOS Events to notify you of the outcome.<br />
The current <strong>INSTEON</strong> Engine does not handle <strong>INSTEON</strong> Groups and Group Cleanup<br />
messages, nor anything involving the <strong>INSTEON</strong> Link Database, although this<br />
functionality is planned for a later version. The SALad coreApp program does handle<br />
these functions at a higher level, however, so you do not have to worry about coding<br />
them yourself.<br />
October 14, 2005 © 2005 Smarthome Technology
Developer’s <strong>Guide</strong> Page 127<br />
IBIOS Software Realtime Clock/Calendar<br />
IBIOS keeps time using a software realtime clock (RTC) that ticks once per second.<br />
Devices that also have a hardware RTC can use it to set the software RTC. The<br />
SALad coreApp Program uses the hardware RTC in The Smarthome PowerLinc<br />
Controller to set the software RTC at power up and also every midnight.<br />
You can set the software RTC manually using the registers shown below, excerpted<br />
from the Flat Memory Map.<br />
Address Register and Bits Description<br />
0x0158 RTC_TIME_H Time since midnight in minutes (MSB, 0-1439)<br />
0x0159 RTC_TIME_L Time since midnight in minutes (LSB, 0-1439)<br />
0x015A RTC_YEAR Year (0-99)<br />
0x015B RTC_MON Month (1-12)<br />
0x015C RTC_DAY Day (1-31, month specific)<br />
0x015D RTC_DOW Day-of-Week bitmap (0SSFTWTM)<br />
0x015E RTC_HOUR Hour (0-23)<br />
0x015F RTC_MIN Minute (0-59)<br />
0x0160 RTC_SEC Second (0-59)<br />
When you set the software RTC, you should also set the RTC_TIME_H,L minutesfrom-midnight<br />
value, because IBIOS will only set it by zeroing it at the next<br />
midnight.<br />
The software RTC handles leap year, but it does not handle daylight-savings time.<br />
CoreApp, however, does handle daylight savings.<br />
October 14, 2005 © 2005 Smarthome Technology
IBIOS X10 Signaling<br />
Developer’s <strong>Guide</strong> Page 128<br />
When IBIOS receives an X10 byte over the powerline, it fires an EVNT_XRX_MSG<br />
(0x08) or EVNT_XRX_XMSG (0x09) IBIOS Event, as explained in IBIOS Event<br />
Details, Note 6. If the SALad coreApp Program or another SALad application with an<br />
appropriate event handler is running, SALad will send an X10 Byte Received<br />
(0x4A) IBIOS Serial Command, as explained in IBIOS Serial Command Details, Note<br />
9.<br />
The manual method for transmitting an X10 Address followed by an X10 Command is<br />
explained in the Send X10 IBIOS Serial Command example.<br />
The following excerpt from the Flat Memory Map shows the registers and flags that<br />
IBIOS uses for sending and receiving X10 bytes.<br />
Address Register and Bits Description<br />
0x0164 X10_RX X10 Receive Buffer<br />
0x0165 X10_TX X10 Transmit Buffer<br />
0x0166<br />
X10_FLAGS X10 Flags<br />
_X10_RTS 7 1=Request To Send<br />
_X10_EXTENDED 5 1=Extended transfer in progress (Tx or Rx)<br />
_X10_TXCOMMAND 3 1=Command, 0=Address for transmit<br />
_X10_RXCOMMAND 2 1=Command, 0=Address for receive<br />
_X10_VALID 1 1=X10 receive valid<br />
To send an X10 byte, place it in the X10_TX buffer, set or clear _X10_TXCOMMAND<br />
to show whether it is an X10 Command or X10 Address, then set the _X10_RTS flag.<br />
To see if there is a new received X10 byte in the X10_TX buffer, inspect the<br />
_X10_VALID flag, or just wait for an EVNT_XRX_MSG (0x08) or<br />
EVNT_XRX_XMSG (0x09) IBIOS Event. Look at _X10_RXCOMMAND to see if the<br />
received byte is an X10 Command or X10 Address, and look at _X10_EXTENDED to<br />
see if it is part of an X10 Extended message.<br />
October 14, 2005 © 2005 Smarthome Technology
IBIOS Input/Output<br />
Developer’s <strong>Guide</strong> Page 129<br />
IBIOS I/O drivers are limited to an IBIOS LED Flasher and an IBIOS SET Button<br />
Handler.<br />
IBIOS LED Flasher<br />
You can control LED flashing using the following registers excerpted from the<br />
Memory Map.<br />
Address Register and Bits Description<br />
0x0168 LED_MODE Bitmap defines flashing pattern for LED<br />
1=On, 0=Off<br />
0x0169 LED_TMR Duration of LED flashing in seconds<br />
0x016A LED_DLY Period between each flash. Defaults to 5, which is 1/8 second<br />
per bit in LED_MODE.<br />
LED_MODE is a bitmap that defines 8 on or off periods for the LED, and LED_DLY<br />
defines how fast the bits are shifted to flash the LED. The default LED_DLY value is<br />
5, which is 1/8 second per bit. Larger values will slow down the flashing.<br />
To flash the LED, load the number of seconds that you want it to flash into LED_TMR.<br />
For example, to flash the LED on and off at half-second intervals for three seconds,<br />
load 0xF0 into LED_MODE and then load 0x03 into LED_TMR.<br />
IBIOS SET Button Handler<br />
Pushing the SET Button generates EVNT_BTN_TAP (0x0A), EVNT_BTN_HOLD<br />
(0x0B), and EVNT_BTN_REL (0x0C) IBIOS Events, as explained in IBIOS Event<br />
Details, Note 7. The TAP_CNT register in the Flat Memory Map. Lets you see how<br />
many times the SET Button was tapped.<br />
Address Register and Bits Description<br />
0x0156 TAP_CNT Counts multiple SET Button taps<br />
October 14, 2005 © 2005 Smarthome Technology<br />
Flat
IBIOS Remote Debugging<br />
Developer’s <strong>Guide</strong> Page 130<br />
You can remotely debug a SALad program with the Debug Report (0x49) IBIOS<br />
Serial Command (see IBIOS Serial Command Details). This is the underlying<br />
mechanism used by the IDE debugger described in the SALad Integrated<br />
Development Environment User’s <strong>Guide</strong>.<br />
Three flags in the NTL_CONTROL register at 0x0076 (see Flat Memory Map) control<br />
IBIOS remote debugging. These flags are bit 7, (_RD_STEP), bit 6 (_RD_HALT), and<br />
bit 5 (_RD_BREAK). A 16-bit address for breakpoints or range checking can be set in<br />
the RD_H and RD_L registers at 0x0026.<br />
Address Register and Bits Description<br />
0x0026 RD_H Remote Debugging breakpoint address MSB<br />
0x0027 RD_L Remote Debugging breakpoint address LSB<br />
0x0076<br />
NTL_CONTROL SALad debugging control flags<br />
_RD_STEP<br />
_RD_HALT<br />
7<br />
6<br />
_RD_HALT _RD_STEP<br />
0 0 Normal execution<br />
0 1 Animation (Trace)<br />
1 0 Execution halted<br />
1 1 Single step requested<br />
_RD_BREAK 5 0=Range Check Mode, 1=Breakpoint Mode<br />
To run a SALad program normally, clear both _RD_HALT and _RD_STEP. This is the<br />
default at power up.<br />
To halt a SALad program as soon as possible, set _RD_HALT and clear _RD_STEP.<br />
Execution will stop after the current instruction executes and a Debug Report<br />
(0x49) IBIOS Serial Command will report the address of the next instruction to be<br />
executed.<br />
To send a Debug Report before every instruction executes, clear _RD_HALT and set<br />
_RD_STEP.<br />
To single-step through a SALad program, set both _RD_HALT and _RD_STEP. This<br />
will cause the next instruction to execute followed by an immediate halt. The halt<br />
will cause a Debug Report to be sent.<br />
To do range checking or to set a breakpoint, load a comparison address into the<br />
RD_H and RD_L registers. If RH_H contains 0x00 (the default power-up condition),<br />
range checking and breakpoints are disabled.<br />
Clear the _RD_BREAK flag to use the comparison address for range checking or else<br />
set _RD_BREAK to use the comparison address as a breakpoint.<br />
If you are range checking and program execution is attempted at a location greater<br />
than the comparison address, execution will be halted, a Debug Report will be sent,<br />
and the IBIOS Watchdog Timer will cause a power-on reset.<br />
If you are using the comparison register for a breakpoint, execution will halt only if<br />
the beginning of the next instruction exactly matches the comparison address.<br />
October 14, 2005 © 2005 Smarthome Technology
Developer’s <strong>Guide</strong> Page 131<br />
You can also do remote debugging over the <strong>INSTEON</strong> network alone by setting the<br />
flag _I_DebugRpt (bit 6) in the I_Control register at 0x0142. This flag is cleared at<br />
power up. When the _I_DebugRpt flag is set, every time a Debug Report (0x49)<br />
IBIOS Serial Command would be sent over a serial connection, a Debug Report<br />
(0x49) <strong>INSTEON</strong> Command from the <strong>INSTEON</strong> Broadcast Command Summary Table<br />
will be sent in an <strong>INSTEON</strong> Broadcast message. You can use <strong>INSTEON</strong> peek and<br />
poke commands from the <strong>INSTEON</strong> Common Command Summary Table to set the<br />
comparison address and the debugging control flags in the remote <strong>INSTEON</strong> device.<br />
IBIOS Watchdog Timer<br />
The watchdog timer in IBIOS is automatic. IBIOS sets appropriate timeout values<br />
for itself and resets the watchdog whenever it returns from a task before the<br />
timeout. If a timeout does occur, the watchdog code performs a power-on reset,<br />
which puts the device in the same state as cycling power does.<br />
There are two ways to force the watchdog timer to cause a reset. One will occur if<br />
you are using IBIOS debugging to do program counter range checking (see IBIOS<br />
Remote Debugging) and the range is exceeded. The other way is to set the _Reset<br />
flag (bit 7) in the Control register at 0x0154 to one (see Flat Memory Map). Both<br />
conditions cause IBIOS to execute an endless loop, which will eventually time out the<br />
watchdog.<br />
You can manually reset the watchdog (buying more time) by setting the _Watchdog<br />
flag (bit 6) in the Control register at 0x0154 to one.<br />
October 14, 2005 © 2005 Smarthome Technology
Developer’s <strong>Guide</strong> Page 132<br />
SALad Language Documentation<br />
The <strong>INSTEON</strong> PowerLinc V2 Controller (PLC) and other planned <strong>INSTEON</strong> devices<br />
contain an embedded language interpreter, called SALad, that allows programming<br />
of complex behavior into SALad-enabled devices. See SALad Applications in the<br />
<strong>INSTEON</strong> Application Development Overview section for a description of the<br />
application development process using SALad.<br />
The SALad language is designed to make execution of <strong>INSTEON</strong> Internal Applications<br />
fast, while keeping the size of the programs small.<br />
SALad is event driven. Examples of events that can occur in a PLC include reception<br />
of an <strong>INSTEON</strong> message or an X10 command, expiration of a timer, or pushing the<br />
SET Button. As events occur, the PLC firmware posts event handles to an event<br />
queue. The firmware then starts the SALad program with the current event handle<br />
located in a specific memory location called NTL_EVENT. The SALad program<br />
inspects NTL_EVENT in order to determine what action to take based on the event<br />
that occurred. Most SALad programming is just a matter of writing event-handling<br />
routines, or modifying the routines found in sample applications.<br />
The SALad Integrated Development Environment (IDE) makes writing and debugging<br />
SALad programs fast and easy. Besides a built-in SALad editor, compiler, and<br />
debugger, the IDE contains an integrated set of <strong>INSTEON</strong>-specific tools that give the<br />
programmer access to every aspect of the <strong>INSTEON</strong> environment.<br />
In This Section<br />
SALad Programming <strong>Guide</strong><br />
Shows the structure of a SALad program, lists sample ‘Hello World’ programs,<br />
and gives tips for developing SALad applications.<br />
SALad Language Reference<br />
Lists the register locations critical to SALad, and describes the SALad instruction<br />
set and addressing modes.<br />
SALad Integrated Development Environment User’s <strong>Guide</strong><br />
Describes a comprehensive software tool used for writing and debugging<br />
embedded SALad applications.<br />
October 14, 2005 © 2005 Smarthome Technology
SALad Programming <strong>Guide</strong><br />
In This Section<br />
Structure of a SALad Program<br />
Describes the basic elements of a SALad program.<br />
Developer’s <strong>Guide</strong> Page 133<br />
The SALad Version of Hello World<br />
Describes a step-by-step re-creation of the classic ‘Hello World’ program in<br />
SALad.<br />
SALad Event Handling<br />
Describes the SALad event handling process.<br />
Hello World 2 – Event Driven Version<br />
Gives the event driven version of a SALad ‘Hello World’ program.<br />
SALad coreApp Program<br />
Describes the default SALad application that comes factory-installed in the PLC.<br />
SALad Timers<br />
Explains how to set up and handle timer events in SALad.<br />
SALad Remote Debugging<br />
Describes how IBIOS and the SALad IDE support SALad program debugging.<br />
Overwriting a SALad Application<br />
Explains how to disable code space write protection in order to download a new<br />
SALad program.<br />
This mechanism is not implemented in PLC firmware versions earlier than 2.10K.<br />
Preventing a SALad Application from Running<br />
Explains how to prevent a SALad program under development from executing<br />
possibly faulty code.<br />
October 14, 2005 © 2005 Smarthome Technology
Structure of a SALad Program<br />
Application Header<br />
Developer’s <strong>Guide</strong> Page 134<br />
All SALad applications require a program header for program verification. This<br />
header can have many pieces of information in it, but it must contain the application<br />
verification data.<br />
Starting at address 0x0210 (see Flat Memory Map), there are 8 bytes of data that<br />
define a region of code that will not be altered during execution. This is used to test<br />
the application for possible corruption.<br />
Address Register and Bits Description<br />
0x0210 ⇒<br />
0x0211<br />
0x0212 ⇒<br />
0x0213<br />
0x0214 ⇒<br />
0x0215<br />
0x0216 ⇒<br />
0x0217<br />
APP_ADDR_TEST Address of range of application for verification test<br />
APP_LEN_TEST Length of range of application for verification test<br />
APP_CHECK_TEST Two’s complement checksum of range of application for<br />
verification test<br />
APP_END Top of currently loaded SALad application. EEPROM is writeprotected<br />
from 0x0200 to the address contained here. Set<br />
0x16B bit 7 to enable over-writing.<br />
APP_ADDR_TEST is the address of the beginning of the application code, normally<br />
0x0230. APP_LEN_TEST is the length of the region to be tested on device<br />
initialization, normally the length of the application. APP_CHECK_TEST is a two’s<br />
complement checksum of that region. If you are using the SALad IDE, it will fill in<br />
this number for you. APP_END is the address of the last byte-plus-one in the<br />
currently loaded application, and is used to write-protect the EEPROM code segment<br />
(see Overwriting a SALad Application).<br />
When the PLC is reset, IBIOS uses the checksum to verify the SALad program before<br />
running it. If it is corrupt, IBIOS will flash the PLC’s LED at about 2 Hz. If the<br />
application is valid, the LED will be lit continuously.<br />
An Application Header structure using literal values might look like this:<br />
ORG 0x210<br />
DATA 0x0230 ; address of beginning of application<br />
DATA 0x000a ; length of application<br />
DATA 0x0041 ; checksum of verification region<br />
DATA 0x023b ; end of application<br />
If you are using the SALad IDE, you can use labels and skip filling in the checksum,<br />
like this:<br />
ORG 0x0210<br />
;=======Application Header================================<br />
DATA Start ;Beginning of application<br />
DATA App_End-Start ;Length of application<br />
DATA 0x00, 0x00 ;Two’s complement checksum<br />
DATA App_End ;End of application<br />
Program Body<br />
The general structure of a SALad program is similar to that of other low-level<br />
assembly programming languages, with varying details depending on the application.<br />
As a stand-alone language, SALad has no specific structural requirements. However,<br />
October 14, 2005 © 2005 Smarthome Technology
Developer’s <strong>Guide</strong> Page 135<br />
most <strong>INSTEON</strong> applications are event-driven, requiring that SALad event handlers<br />
follow a definite structural organization.<br />
For a simple direct SALad application, start the program at 0x0237, which is the<br />
standard entry vector for Static IBIOS Events. When the PLC is reset (either by<br />
power cycling or a reset command), the SALad application will be started with an<br />
initialization EVNT_INIT (0x00) IBIOS Event posted to the event queue.<br />
It is possible to write a SALad application without event handlers, but you must then<br />
poll all hardware for a change of state, and SALad Timers will not work without event<br />
processing.<br />
By far the easiest way to write SALad applications is use the IDE as explained in the<br />
SALad Integrated Development Environment User’s <strong>Guide</strong> to modify the event<br />
handlers in the open-source SALad coreApp Program.<br />
October 14, 2005 © 2005 Smarthome Technology
The SALad Version of Hello World<br />
Developer’s <strong>Guide</strong> Page 136<br />
The SALad language contains general commands that are useful for most SALadenabled<br />
<strong>INSTEON</strong> products. Any commands that are unique to a subset of the<br />
product line are provided through the API (Application Program Interface) feature.<br />
This allows custom firmware and commands to be added to the SALad language<br />
without altering the core SALad engine.<br />
In this example, the RS232 port is utilized to send a Hello World! ASCII message.<br />
Because the RS232 port is not found in all the Smarthome products, these<br />
commands are provided as API calls. In this case, we will use the API_RS_SendStr<br />
command which has a command code of 0x82. The format of this command is the<br />
API code (0x0A) followed by the command code (0x82) followed by the 2-byte<br />
address of the data containing the message to send.<br />
When this example is executed, the output will be to the RS232 Port at 4800 Baud, 8<br />
bits, 1 stop bit, and no parity. The application looks like this:<br />
ORG 0x0210<br />
;=======Application Header================================<br />
DATA Start ;Beginning of application<br />
DATA App_End-Start ;Length of application<br />
DATA 0x00, 0x00 ;Two’s complement checksum<br />
DATA App_End ;End of application<br />
ORG 0x0237<br />
;=======Application Code==================================<br />
Start<br />
API 0x82, Message ;Send Message to RS232 port<br />
JUMP Start ;Loop non-stop<br />
Message<br />
DATA "Hello "<br />
DATA "World!"<br />
DATA 0x0D,0x0A,0x00 ;Zero terminates string<br />
App_End<br />
October 14, 2005 © 2005 Smarthome Technology
SALad Event Handling<br />
Developer’s <strong>Guide</strong> Page 137<br />
As events occur, IBIOS posts messages to a message queue that the SALad<br />
application can respond to for processing. When SALad is idle, the event processor<br />
continually looks for new events to process. When one appears, IBIOS puts the<br />
Event Handle in the NTL_EVENT register and then calls SALad at one of two possible<br />
vectors:<br />
0x0230 – for Timer Events (see SALad Timers)<br />
0x0237 – for Static Events (see IBIOS Events)<br />
Upon entry, the SALad application must process the event handle in NTL_EVENT in<br />
order to run the correct event handler. In the following code, taken from the SALad<br />
coreApp Program, the event handle is used as an index into a table of addresses that<br />
point to the beginning of the event handling routines.<br />
;=======Register Definitions==============================<br />
APP_TMP_H EQU 0x006E ;These stay alive only until<br />
APP_TMP_L EQU 0x006F ;the first CALL. They are<br />
;used for the Event handler.<br />
ORG 0x0210<br />
;=======Application Header================================<br />
DATA Start ;Beginning of application<br />
DATA App_End-Start ;Length of application<br />
DATA 0x00, 0x00 ;Two’s complement checksum<br />
ORG 0x0230<br />
;=======Event Process Code================================<br />
Start<br />
StartTimer<br />
JUMP ProcessTimer ;jump to Timer process<br />
StartEvent<br />
MOVE NTL_EVENT, APP_TMP_L ;setup event offset<br />
MUL #0x0002, APP_TMP_H ;multiply by 2 for<br />
;word offset (16bit)<br />
ADD #EventJmpTbl, APP_TMP_H ;add table address 0243:<br />
;to offset (16bit)<br />
JUMP ProcessEvent ;process table entry<br />
ProcessTimer<br />
MOVE NTL_EVENT, APP_TMP_L ;setup event offset<br />
MUL #0x0002, APP_TMP_H ;multiply by 2 for<br />
;word offset (16bit)<br />
ADD<br />
ProcessEvent<br />
#EventJmpTbl,APP_TMP_H ;add table address 0256:<br />
;to offset (16bit)<br />
MOVE$ @APP_TMP_H,APP_TMP_H,2 ;get indirect pointer<br />
;from table<br />
JUMP<br />
EventJmpTbl<br />
@APP_TMP_H ;execute code at table<br />
;entry<br />
DATA Event00 ;EVNT_INIT<br />
DATA Event01 ;EVNT_IRX_MSG<br />
DATA Event02 ;EVNT_IRX_NACK<br />
DATA Event03 ;EVNT_XRX_MSG<br />
DATA Event04 ;EVNT_XRX_XMSG<br />
DATA Event05 ;EVNT_BTN_TAP<br />
DATA Event06 ;EVNT_BTN_HOLD<br />
DATA Event07 ;EVNT_BTN_REL<br />
DATA Event08 ;EVNT_ALARM<br />
DATA Event09 ;EVNT_MIDNIGHT<br />
DATA Event0A ;EVNT_2AM<br />
October 14, 2005 © 2005 Smarthome Technology
DATA Event0B ;EVNT_SRX_COM<br />
TimerJmpTbl<br />
DATA 0x00, 0x00 ;No Timer Events<br />
;=======Static Events==============================<br />
;-------EVNT_INIT<br />
Event00<br />
END<br />
;-------EVNT_IRX_MSG<br />
Event01<br />
END<br />
;-------EVNT_IRX_NACK<br />
Event02<br />
END<br />
;-------EVNT_XRX_MSG<br />
Event03<br />
END<br />
;-------EVNT_XRX_XMSG<br />
Event04<br />
END<br />
;-------EVNT_BTN_TAP<br />
Event05<br />
END<br />
;-------EVNT_BTN_HOLD<br />
Event06<br />
END<br />
;-------EVNT_BTN_REL<br />
Event07<br />
END<br />
;-------EVNT_ALARM<br />
Event08<br />
END<br />
;-------EVNT_MIDNIGHT<br />
Event09<br />
END<br />
;-------EVNT_2AM<br />
Event0A<br />
END<br />
;-------EVNT_SRX_COM - Serial Received a command<br />
Event0B<br />
END<br />
;======Timer Events================================<br />
; No Timer Events<br />
App_End<br />
Developer’s <strong>Guide</strong> Page 138<br />
October 14, 2005 © 2005 Smarthome Technology
Developer’s <strong>Guide</strong> Page 139<br />
Hello World 2 – Event Driven Version<br />
The following example shows the “Hello World” program implemented as an event<br />
driven process. This version prints “Hello World!” out the RS232 port each time the<br />
SET Button is pressed. This demonstrates the processing of the EVNT_BTN_TAP<br />
(0x0A) and EVNT_BTN_HOLD (0x0B) IBIOS Events that are generated when the<br />
button is tapped or held. If the button is pressed for more than 350 ms, the<br />
program will send “Good-Bye World!” instead.<br />
When this example is executed, the output will be to the RS232 Port at 4800 Baud, 8<br />
bits, 1 stop bit, and no parity. The program is a simple modification of the SALad<br />
coreApp Program event processor shown in SALad Event Handling.<br />
;=======Register Definitions==============================<br />
APP_TMP_H EQU 0x006E ;These stay alive only until<br />
APP_TMP_L EQU 0x006F ;the first CALL. They are<br />
;used for the Event handler.<br />
ORG 0x0210<br />
;=======Application Header================================<br />
DATA Start ;Beginning of application<br />
DATA App_End-Start ;Length of application<br />
DATA 0x00, 0x00 ;Two’s complement checksum<br />
ORG 0x0230<br />
;=======Event Process Code================================<br />
Start<br />
StartTimer<br />
JUMP ProcessTimer ;jump to Timer process<br />
StartEvent<br />
MOVE NTL_EVENT, APP_TMP_L ;setup event offset<br />
MUL #0x0002, APP_TMP_H ;multiply by 2 for<br />
;word offset (16bit)<br />
ADD #EventJmpTbl, APP_TMP_H ;add table address 0243:<br />
;to offset (16bit)<br />
JUMP ProcessEvent ;process table entry<br />
ProcessTimer<br />
MOVE NTL_EVENT, APP_TMP_L ;setup event offset<br />
MUL #0x0002, APP_TMP_H ;multiply by 2 for<br />
;word offset (16bit)<br />
ADD #EventJmpTbl,APP_TMP_H ;add table address 0256:<br />
;to offset (16bit)<br />
ProcessEvent<br />
MOVE$ @APP_TMP_H,APP_TMP_H,2 ;get indirect pointer<br />
;from table<br />
JUMP @APP_TMP_H ;execute code at table<br />
;entry<br />
EventJmpTbl<br />
DATA Event00 ;EVNT_INIT<br />
DATA Event01 ;EVNT_IRX_MSG<br />
DATA Event02 ;EVNT_IRX_NACK<br />
DATA Event03 ;EVNT_XRX_MSG<br />
DATA Event04 ;EVNT_XRX_XMSG<br />
DATA Event05 ;EVNT_BTN_TAP<br />
DATA Event06 ;EVNT_BTN_HOLD<br />
DATA Event07 ;EVNT_BTN_REL<br />
DATA Event08 ;EVNT_ALARM<br />
DATA Event09 ;EVNT_MIDNIGHT<br />
DATA Event0A ;EVNT_2AM<br />
DATA Event0B ;EVNT_SRX_COM<br />
TimerJmpTbl<br />
October 14, 2005 © 2005 Smarthome Technology
DATA 0x00, 0x00 ;No Timer Events<br />
;=======Static Events==============================<br />
;-------EVNT_INIT<br />
Event00<br />
END<br />
;-------EVNT_IRX_MSG<br />
Event01<br />
END<br />
;-------EVNT_IRX_NACK<br />
Event02<br />
END<br />
;-------EVNT_XRX_MSG<br />
Event03<br />
END<br />
;-------EVNT_XRX_XMSG<br />
Event04<br />
END<br />
;-------EVNT_BTN_TAP<br />
Event05<br />
API 0x82, Message1 ;Send Message to RS232 port<br />
END<br />
;-------EVNT_BTN_HOLD<br />
Event06<br />
API 0x82, Message2 ;Send Message to RS232 port<br />
END<br />
;-------EVNT_BTN_REL<br />
Event07<br />
END<br />
;-------EVNT_ALARM<br />
Event08<br />
END<br />
;-------EVNT_MIDNIGHT<br />
Event09<br />
END<br />
;-------EVNT_2AM<br />
Event0A<br />
END<br />
;-------EVNT_SRX_COM - Serial Received a command<br />
Event0B<br />
END<br />
;======Timer Events================================<br />
; No Timer Events<br />
Message1<br />
DATA "Hello "<br />
DATA "World!"<br />
DATA 0x0D,0x0A,0x00 ;Zero terminates string<br />
Message2<br />
DATA "GoodBye "<br />
DATA "World!"<br />
DATA 0x0D,0x0A,0x00 ;Zero terminates string<br />
App_End<br />
Developer’s <strong>Guide</strong> Page 140<br />
October 14, 2005 © 2005 Smarthome Technology
SALad coreApp Program<br />
Developer’s <strong>Guide</strong> Page 141<br />
As shipped by Smarthome, the PowerLinc V2 Controller (PLC) contains a 1200-byte<br />
SALad program called coreApp that performs a number of useful functions:<br />
• When coreApp receives messages from <strong>INSTEON</strong> devices, it sends them to the<br />
computing device via its serial port, and when it receives <strong>INSTEON</strong>-formatted<br />
messages from the computing device via the serial port, it sends them out over<br />
the <strong>INSTEON</strong> network.<br />
• CoreApp handles linking to other <strong>INSTEON</strong> devices and maintains a<br />
Database.<br />
PLC Link<br />
• CoreApp is event-driven, meaning that it can send messages to the computing<br />
device based on IBIOS Events and SALad Timers.<br />
• CoreApp can send and receive X10 commands.<br />
• CoreApp sets the software realtime clock using the hardware realtime clock and<br />
handles daylight savings time.<br />
Several of the IBIOS Events listed in the IBIOS Event Summary Table and IBIOS<br />
Serial Commands listed in the IBIOS Serial Command Summary Table require SALad<br />
event handlers like those in coreApp in order to ensure realtime execution.<br />
Source code for coreApp is available to developers to modify for their own purposes.<br />
Using the tools described in the SALad Integrated Development Environment User’s<br />
<strong>Guide</strong> to modify coreApp is by far the easiest way to develop your own SALad<br />
applications. Once programmed with an appropriately modified SALad App, the PLC<br />
can operate on its own without being connected to a computing device.<br />
October 14, 2005 © 2005 Smarthome Technology
SALad Timers<br />
Developer’s <strong>Guide</strong> Page 142<br />
You can set up a SALad Timer Event by loading 2 bytes into a timer buffer. The first<br />
byte, called the Timer Index, is the number of the timer handler routine that you<br />
want to execute when the Timer Event fires. The second byte, called the Timer<br />
Time, designates how much time you want to elapse from the time you set up the<br />
Timer Event until the Timer Event fires. If the high bit of Timer Time is 0, the other<br />
7 bits designate 1 to 127 seconds; if the high bit is 1, the other 7 bits designate 1 to<br />
127 minutes. A Timer Time of 0x00 designates that the timer is disabled.<br />
The default number of co-pending Timer Events that you can set up is four. If you<br />
need more Timer Events, increase the pointer value stored in NTL_BUFFER at<br />
0x0033 (see Flat Memory Map)<br />
by two for each additional Timer Event you want to<br />
support. NTL_BUFFER points to the end of the timer buffer, which begins at 0x0046.<br />
You need to write a SALad timer handler routine for each Timer Index that you will<br />
be using. Timer Index 1 will fire the first handler, Timer Index 2 will fire the second<br />
handler, and so on.<br />
There are four SALad instructions for setting up and removing Timer Events (see<br />
Two-byte SALad Instructions):<br />
ONESHOT (Timer Index, Timer Time)<br />
Set up a new Timer Event if there is no pre-existing Timer Event with the same<br />
Timer Index. If there is such a Timer Event, replace its Timer Time value. After<br />
this Timer Event fires, remove it by setting its Timer Index to 0x00.<br />
TIMER (Timer Index, Timer Time)<br />
Set up a new Timer Event if there is no pre-existing Timer Event with the same<br />
Timer Index. If there is such a Timer Event, replace its Timer Time value. After<br />
this Timer Event fires, disable it by setting its Timer Time to 0x00, but do not<br />
remove it.<br />
TIMERS (Timer Index, Timer Time)<br />
Set up a new Timer Event unconditionally. After this Timer Event fires, disable it<br />
by setting its Timer Time to 0x00, but do not remove it.<br />
KILL (Timer Index)<br />
If there is a pre-existing Timer Event with the same Timer Index, remove it by<br />
setting its Timer Index to 0x00.<br />
If you try to set up a Timer Event but there is no room in the timer buffer, the Timer<br />
Event will not be set up. If this happened, the _NTL_BO buffer overrun flag (bit 1) of<br />
NTL_STAT at 0x0075 will be 1.<br />
October 14, 2005 © 2005 Smarthome Technology
SALad Remote Debugging<br />
Developer’s <strong>Guide</strong> Page 143<br />
It is possible to debug SALad applications remotely using either Serial (RS232 or<br />
USB) or <strong>INSTEON</strong> communications. IBIOS provides the necessary support. See<br />
IBIOS Remote Debugging for a full explanation of how this works at the low level.<br />
The comprehensive debugging features built into the SALad IDE (see the SALad<br />
Integrated Development Environment User’s <strong>Guide</strong>) are built on this low level IBIOS<br />
mechanism. Therefore, the easiest way to take advantage of remote SALad<br />
debugging is to use the SALad IDE.<br />
Overwriting a SALad Application<br />
SALad code in EEPROM is write-protected from 0x0200 to the top of the SALad<br />
application pointed to by APP_END, as shown in the Flat Memory Map excerpt below.<br />
You must set the _RS_AppLock flag before you attempt to write to this area.<br />
Address Register and Bits Description<br />
0x016B<br />
0x0216 ⇒<br />
0x0217<br />
RS_CONTROL Control flags for serial command interpreter<br />
_RS_AppLock 3 1=Enable overwriting of SALad code from 0x0200 to end of<br />
SALad App given in 0x0216 and 0x0217<br />
APP_END Top of currently loaded SALad application. EEPROM is writeprotected<br />
from 0x0200 to the address contained here. Set<br />
0x16B bit 7 to enable over-writing.<br />
This mechanism is not implemented in PLC firmware versions earlier than 2.10K.<br />
Preventing a SALad Application from Running<br />
While developing a SALad application that runs on the PLC, you may need to<br />
manually prevent the SALad code from executing, because of faulty SALad code that<br />
prevents serial communication.<br />
To prevent SALad execution while allowing IBIOS to run normally, remove and then<br />
re-apply power to the PLC while holding down the SET Button for 5 seconds. IBIOS<br />
will then write the complement of the SALad program’s checksum to the SALad<br />
checksum verification register. Since the SALad program’s checksum will not match<br />
the complemented checksum, the SALad program will not run.<br />
To restore the SALad checksum verification register to its correct value, just<br />
complement it again by repeating the ‘apply power while holding the SET Button for<br />
5 seconds’ procedure.<br />
October 14, 2005 © 2005 Smarthome Technology
SALad Language Reference<br />
In This Section<br />
SALad Memory Addresses<br />
Describes SALad’s usage of memory.<br />
Developer’s <strong>Guide</strong> Page 144<br />
SALad Instruction Set<br />
Documents all SALad instructions and addressing modes.<br />
October 14, 2005 © 2005 Smarthome Technology
SALad Memory Addresses<br />
Developer’s <strong>Guide</strong> Page 145<br />
SALad uses the same Flat Memory Addressing as IBIOS. See the Flat Memory Map<br />
for a table of important memory locations.<br />
See Structure of a SALad Program for the location of the SALad program itself and<br />
the structure of its header.<br />
SALad program flags appear in the register NTL_STAT as follows:<br />
Address Register and Bits Description<br />
0x0075<br />
NTL_STAT SALad Status Register<br />
_DB_END 4 1=Enrollment Link Database search reached end of database<br />
_DB_PASS 3 1=Enrollment Link Database search successful<br />
_NTL_DZ 2 1=Divide by Zero<br />
_NTL_BO 1 1=Buffer Overrun<br />
_NTL_CY 0 1=Carry from Math and Test operations<br />
October 14, 2005 © 2005 Smarthome Technology
SALad Instruction Set<br />
Developer’s <strong>Guide</strong> Page 146<br />
The SALad instructions are designed to support all the processing needs of a basic<br />
programming language. Additional device-specific functions can be defined using<br />
Application Programming Interface (API) calls to firmware.<br />
SALad universally supports access to or from RAM or EEPROM directly or indirectly.<br />
Literal data can be provided for immediate operations. The Compare and Move<br />
instructions have a block mode to perform string compares or block moves.<br />
Indirect addressing modes support address pointers and jump tables.<br />
In This Section<br />
SALad Universal Addressing Module (UAM)<br />
Describes addressing modes of SALad instructions.<br />
SALad Parameter Encoding<br />
Describes how parameters for SALad instructions are encoded.<br />
SALad Instruction Summary Table<br />
Describes SALad instructions and parameters.<br />
October 14, 2005 © 2005 Smarthome Technology
Developer’s <strong>Guide</strong> Page 147<br />
SALad Universal Addressing Module (UAM)<br />
The UAM is a mechanism for encoding addressing mode and parameter information<br />
in the instructions. The commands have UAM-specific information in the low nibble<br />
of the instruction. These bits define what kind of memory is being accessed and the<br />
number of parameter bytes.<br />
SALad instructions use Full-UAM, Half-UAM, or No-UAM encodings. Full-UAM<br />
instructions take two parameters, Half-UAM instructions take one parameter, and<br />
No-UAM instructions do not use the UAM at all and have no parameters.<br />
These tables show how SALad instructions are UAM-encoded in a byte:<br />
Command<br />
Full-UAM SALad Instruction<br />
Source<br />
Parameter<br />
Destination<br />
Parameter<br />
Mode<br />
Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0<br />
4-bit command identifier<br />
0=8 bit<br />
Parameter<br />
1=16 bit<br />
Parameter<br />
Half-UAM SALad Instruction<br />
0=8 bit<br />
Parameter<br />
1=16 bit<br />
Parameter<br />
00 = Direct to Direct<br />
01 = Direct to Indirect<br />
10 = Indirect to Direct<br />
11 = Literal to Direct<br />
Command Mode<br />
Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0<br />
7-bit command identifier<br />
No-UAM SALad Instruction<br />
Command<br />
0=Direct<br />
1=Indirect<br />
Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0<br />
8-bit command identifier<br />
October 14, 2005 © 2005 Smarthome Technology
SALad Parameter Encoding<br />
Parameters are of types:<br />
• Register<br />
• Direct<br />
• Indirect<br />
• 8-bit Literal Value<br />
• 16-bit Literal Value<br />
Developer’s <strong>Guide</strong> Page 148<br />
A Register parameter is an 8-bit location in memory that is referenced by an offset<br />
that is added to a base value stored in NTL_EVENT.<br />
A Direct parameter is a parameter that is referenced by a 16-bit address in the<br />
Memory Map.<br />
An Indirect parameter is a pointer to a location in memory.<br />
Literal values are constant values that are coded directly into the program.<br />
In This Section<br />
Parameter Reference Tables<br />
Contains reference tables for encoding SALad instructions.<br />
October 14, 2005 © 2005 Smarthome Technology<br />
Flat
Parameter Reference Tables<br />
Parameter Types<br />
Developer’s <strong>Guide</strong> Page 149<br />
This table shows the types of parameters described above, whether they are 8 or 16bit,<br />
whether they refer to addresses relative to the Program Counter or relative to<br />
the Absolute address in the Flat Memory Map, and whether they are Indirect or<br />
Direct.<br />
Ref Description 8-bit or 16-bit Relative or<br />
Absolute<br />
Indirect or<br />
Direct<br />
Rn Direct Register Mode (n + NTL_REG) 8-bit Absolute Direct<br />
@Rn Indirect Register Mode (n + NTL_REG) 8-bit Absolute Indirect<br />
D Direct Mode (PC + D) 16-bit Relative Direct<br />
@D Indirect Mode (PC + D) 16-bit Relative Indirect<br />
#8 8-bit Literal 8-bit Absolute Direct<br />
#16 16-bit Literal 16-bit Absolute Direct<br />
Full-UAM Instruction Encoding<br />
This table shows how to encode the low nibble for full UAM instructions (i.e.<br />
instructions that take both source and destination parameters). Parameter<br />
references are from the table above.<br />
Command and Parameters Instruction<br />
Code<br />
Command and Parameters Instruction<br />
Code<br />
Command Rn, Rn 0x?0 Command D, Rn 0x?8<br />
Command Rn, @Rn 0x?1 Command D, @Rn 0x?9<br />
Command @Rn, Rn 0x?2 Command @D, Rn 0x?A<br />
Command #8, Rn 0x?3 Command #16, Rn 0x?B<br />
Command Rn, D 0x?4 Command D, D 0x?C<br />
Command Rn, @D 0x?5 Command D, @D 0x?D<br />
Command @Rn, D 0x?6 Command @D, D 0x?E<br />
Command #8, D 0x?7 Command #16, D 0x?F<br />
Half-UAM Instruction Encoding<br />
This table shows how to encode half UAM instructions (i.e. instructions that take only<br />
a destination parameter). Parameter references are from the table above.<br />
Instruction Code is shown as 8-bit pattern.<br />
Command and Parameters Instruction<br />
Code<br />
Command and Parameters Instruction<br />
Code<br />
Command D xxxxxxx0 Command @D xxxxxxx1<br />
October 14, 2005 © 2005 Smarthome Technology
SALad Instruction Summary Table<br />
One-byte SALad Instructions<br />
Developer’s <strong>Guide</strong> Page 150<br />
Command Code UAM Parameters Description<br />
NOP 0x00 None No Operation<br />
RET 0x01 None Return from call<br />
END 0x02 None Return to System<br />
Function 0x03 None Enable extended function<br />
mode<br />
API 0x04 None Execute external firmware<br />
routines<br />
8BIT 0x05 None Select 8 bit processing<br />
16BIT 0x06 None Select 16 bit processing<br />
HALT 0x07 None Halt SALad execution<br />
RL 0x08⇒0x09 Half-UAM Rotate Left value stored in<br />
dest by 1-bit<br />
RR 0x0A⇒0x0B Half-UAM Rotate Right value stored in<br />
dest by 1-bit<br />
JUMP 0x0C⇒0x0D Half-UAM Jump to specified<br />
destination relative to PC<br />
CALL 0x0E⇒0x0F Half-UAM Call routine at specified<br />
destination relative to PC<br />
TEST 0x10⇒0x1F Half-UAM Test bit in byte at<br />
destination, jump if false<br />
CLR 0x20⇒0x2F Half-UAM Clear bit in byte at<br />
destination<br />
SET 0x30⇒0x3F Half-UAM Set bit in byte at<br />
destination<br />
ADD 0x40⇒0x4F Full-UAM Add source to destination,<br />
store result in destination<br />
OR 0x50⇒0x5F Full-UAM OR source to destination,<br />
store result in destination<br />
AND 0x60⇒0x6F Full-UAM AND source to destination,<br />
store result in destination<br />
XOR 0x70⇒0x7F Full-UAM XOR source to destination,<br />
store result in destination<br />
COMP> 0x80⇒0x8F Full-UAM Compare source greater to<br />
destination, jump if false<br />
COMP< 0x90⇒0x9F Full-UAM Compare source less than<br />
destination, jump if false<br />
October 14, 2005 © 2005 Smarthome Technology
Developer’s <strong>Guide</strong> Page 151<br />
Command Code UAM Parameters Description<br />
LOOP- 0xA0⇒0xAF Full-UAM Decrement destination,<br />
branch while greater than<br />
source<br />
LOOP+ 0xB0⇒0xBF Full-UAM Increment destination,<br />
branch while less than<br />
source<br />
MOVE 0xC0⇒0xCF Full-UAM Move source to destination<br />
COMP= 0xD0⇒0xDF Full-UAM Compare source equal to<br />
destination, jump if false<br />
SUB 0xE0⇒0xEF Full-UAM Subtract source from<br />
destination, store result in<br />
destination<br />
October 14, 2005 © 2005 Smarthome Technology
Two-byte SALad Instructions<br />
These are Extended Commands, preceded by 0x03.<br />
Developer’s <strong>Guide</strong> Page 152<br />
Command Code UAM Parameters Description<br />
ENROLL 0x03 0x00 None Enable Enrollment for 2 minutes<br />
Starts 2-minute enrollment timer and<br />
enables Enrollment command passthrough.<br />
a. Button must be pushed when this<br />
command is executed<br />
b. Timer is restarted when valid enrollment<br />
command is received<br />
c. Enrollment command generates a<br />
unique event: EVNT_IRX_ENROLL or 0x07<br />
NEXT 0x03 0x01 None Find next group in Link Database<br />
SEND 0x03 0x02 None Send <strong>INSTEON</strong><br />
ENDPROC 0x03 0x03 None Skip parameter on stack and return<br />
KILL 0x03 0x04 None Delete pending timer event specified by<br />
index from event queue<br />
PAUSE 0x03 0x05 None Pause for time in 25ms increments<br />
October 14, 2005 © 2005 Smarthome Technology
Developer’s <strong>Guide</strong> Page 153<br />
Command Code UAM Parameters Description<br />
FIND 0x03 0x06 None Find record in database. These bits define<br />
the field(s) of the record that you are<br />
searching for in the Enrollment database.<br />
Flags is defined as:<br />
DB_FLAGS<br />
76543210<br />
XXXXXXXX<br />
ID0-------------+|||||||<br />
ID1--------------+||||||<br />
ID2---------------+|||||<br />
Group--------------+||||<br />
Linear Search-------+|||<br />
Mode-----------------++|<br />
<strong>INSTEON</strong> Master/Slave---+<br />
Search Mode (Mode bits):<br />
00 Deleted<br />
01 Other<br />
10 <strong>INSTEON</strong> Slave<br />
11 <strong>INSTEON</strong> Master<br />
DB_Flags configuration examples:<br />
EMPTY EQU 0x00 ; look for empty slot<br />
; index is in DB_H<br />
SLAVE EQU 0xE4 ; match ID, look for<br />
; SLAVE, ID is in<br />
; RxFrom0-RxFrom2<br />
MASTER EQU 0xE6 ; match ID, look for<br />
; MASTER, ID is in<br />
; RxFrom0-RxFrom2<br />
<strong>INSTEON</strong> EQU 0xE5; match ID, look for<br />
; MASTER or SLAVE,<br />
; ID is in RxFrom0-<br />
; RxFrom2<br />
MEMBER EQU 0x1C ; match group, look<br />
; for SLAVE, index<br />
; is in DB_0<br />
GROUP EQU 0xF6 ; match ID and group,<br />
; look for MASTER, ID<br />
; is in RxFrom0-<br />
; RxFrom2, group is<br />
; in RxTo2<br />
To Find a member of a local group, set<br />
group number in DB_3 and execute:<br />
FIND MEMBER<br />
To Find either a Master or Slave <strong>INSTEON</strong><br />
record that matches the received<br />
message, execute:<br />
FIND <strong>INSTEON</strong><br />
X10 0x03 0x08 None Send X10 message<br />
October 14, 2005 © 2005 Smarthome Technology
Developer’s <strong>Guide</strong> Page 154<br />
Command Code UAM Parameters Description<br />
LED 0x03 0x09 None Flash LED; Pattern defines the blinking<br />
pattern, and time specifies the duration of<br />
the blinking from 0 to 255 seconds. For<br />
example: LED 0x55 0x0A would make the<br />
LED blink at 8Hz for 10 seconds; The delay<br />
between blinks can be controlled by<br />
writing to LED_DLY<br />
RANDOM 0x03 0x0A None Generates random number between 0 and<br />
limit and stores in register<br />
RANDOMIZE 0x03 0x0B None Get next random number from generator<br />
using 16 bit absolute address to an 8-bit<br />
seed value and stores in NTL_RND<br />
ONESHOT 0x03 0x0C None Set One-Shot timer: Index is the event<br />
number that the firmware stores in<br />
NTL_EVENT when the timer expires; Time<br />
is 0⇒127 seconds, or 2 minutes 8 seconds<br />
⇒ 130 minutes 8 seconds if MSb is set.<br />
TIMER 0x03 0x0D None Set or Reset timer<br />
TIMERS 0x03 0x0E None Set multiple timers<br />
Undefined 0x03 0x0F None<br />
X10EXT 0x03 0x10⇒<br />
0x03 0x11<br />
SEND$ 0x03 0x20 ⇒<br />
0x03 0x21<br />
SENDEXT$ 0x03 0x30 ⇒<br />
0x03 0x31<br />
MUL 0x03 0x50⇒<br />
0x03 0x5F<br />
DIV 0x03 0x60⇒<br />
0x03 0x6F<br />
MOD 0x03 0x70⇒<br />
0x03 0x7F<br />
PROC 0x03 0x80⇒<br />
0x03 0x8F<br />
MASK 0x03 0x90⇒<br />
0x03 0x9F<br />
COMP$> 0x03 0xA0⇒<br />
0x03 0xAF<br />
COMP$< 0x03 0xB0⇒<br />
0x03 0xBF<br />
TJUMP 0x03 0xC0⇒<br />
0x03 0xCF<br />
Half-UAM Additional data for extended X10 message<br />
Half-UAM Send 9 byte <strong>INSTEON</strong> message located at<br />
destination (from ID is inserted<br />
automatically)<br />
Half-UAM Send 23 byte <strong>INSTEON</strong> message located at<br />
destination (from ID is inserted<br />
automatically)<br />
Full-UAM Multiply source to destination, store result<br />
in destination and destination +1<br />
Full-UAM Divide source into destination, store result<br />
in destination<br />
Full-UAM Divide source into destination, store<br />
remainder in destination<br />
Full-UAM Place source on stack and call destination,<br />
jump if _NTL_CY=0 upon return<br />
Full-UAM AND source to destination, jump if zero<br />
Full-UAM <br />
<br />
Full-UAM <br />
<br />
Full-UAM <br />
source: <br />
dest: <br />
limit: <br />
Compare source string greater to<br />
destination string, jump if false<br />
Compare source string less than<br />
destination string, jump if false<br />
Increment destination, branch while less<br />
than source<br />
October 14, 2005 © 2005 Smarthome Technology
Developer’s <strong>Guide</strong> Page 155<br />
Command Code UAM Parameters Description<br />
TCALL 0x03 0xD0⇒<br />
0x03 0xDF<br />
Full-UAM <br />
source: <br />
dest: <br />
limit: <br />
Decrement destination, branch while<br />
greater than source<br />
October 14, 2005 © 2005 Smarthome Technology
Developer’s <strong>Guide</strong> Page 156<br />
SALad Integrated Development<br />
Environment User’s <strong>Guide</strong><br />
The SALad Integrated Development Environment (IDE) is a powerful tool for<br />
developing applications to run on SALad-enabled <strong>INSTEON</strong> devices. For information<br />
about the SALad Language, refer to the SALad Programming and SALad Language<br />
Reference sections below.<br />
The SALad IDE’s source code editor handles multiple files, using color to indicate<br />
code context. In debug mode, programmers can use single-stepping, breakpoints,<br />
tracing, and watches to find and fix coding errors quickly.<br />
At the heart of the IDE is The SALad Compiler, which reads SALad language source<br />
files and creates SALad object code, along with an error listing and symbol map.<br />
Compiled object code can either be serially downloaded to a real Smarthome<br />
PowerLinc V2 Controller (PLC) plugged into the powerline, or else it can be run on a<br />
virtual PLC simulated in software. Besides the virtual PLC, the IDE can also simulate<br />
a virtual powerline environment with any number of virtual LampLinc devices<br />
plugged into it, so that developers can create and test complex SALad applications<br />
on a standalone PC before validating them in a real <strong>INSTEON</strong> environment.<br />
Using an integrated set of <strong>INSTEON</strong>-specific tools, programmers can compose and<br />
monitor <strong>INSTEON</strong>, X10, ASCII, or raw data messages, simulate PLC or realtime<br />
clock/calendar events, and directly manipulate the PLC’s Link Database, all without<br />
ever leaving the IDE.<br />
In This Section<br />
SALad IDE Quickstart<br />
Explains how to get started using the SALad IDE right away.<br />
IDE Main Window<br />
Describes the IDE’s main menus and toolbar.<br />
IDE Editor<br />
Gives the features of the IDE’s Editor.<br />
IDE Watch Panel<br />
Explains how to use Watches during debugging.<br />
IDE Options Dialog Box<br />
Discusses the IDE’s setup options.<br />
IDE Windows and Inspectors<br />
Explains the many additional tools available in the IDE.<br />
IDE Virtual Devices<br />
Describes how to use the software PLC Simulator, Virtual Powerline, and Virtual<br />
LampLinc.<br />
IDE Keyboard Shortcuts<br />
Shows how to use the keyboard to perform common actions in the IDE.<br />
October 14, 2005 © 2005 Smarthome Technology
SALad IDE Quickstart<br />
Developer’s <strong>Guide</strong> Page 157<br />
Follow these steps to get familiar with the IDE quickly. The IDE works with a<br />
Smarthome PowerLinc V2 Controller, called a PLC for short. You can either use a<br />
real PLC plugged into the powerline and connected to your PC via a USB or RS232<br />
serial port, or else the IDE can simulate a virtual PLC in software. This quick tutorial<br />
will get you connected to the PLC, then guide you through compiling, downloading,<br />
testing and debugging a sample ‘Hello World’ SALad program<br />
1. Connect the PowerLinc Controller.<br />
If you are using a real PLC, connect a USB or RS232 serial cable from it to your<br />
Windows PC, and then plug the PLC into an electrical outlet.<br />
If you wish to use the PLC Simulator instead, simply turn it on by selecting PLC<br />
Simulator from the IDE’s Mode menu.<br />
2. Run the SALad IDE.<br />
After installing the SALad IDE on your Windows PC, go to Start->Programs-<br />
>SALad IDE->SALad IDE to launch the program.<br />
3. Test the serial connection to the PLC.<br />
When you run the IDE for the first time, a Startup Wizard will automatically help<br />
you test the serial connection to the PLC. You can also launch the Startup Wizard<br />
from the View menu.<br />
If you would rather test the serial connection to the PLC manually, follow these<br />
steps:<br />
a. Click the Edit->Application Options menu item. An Options dialog box will<br />
appear.<br />
b. Under the Communications tab, select either USB or the COM (RS232)<br />
port you are using to connect to the PLC. If you are using the PLC<br />
Simulator, it does not matter what you select here.<br />
c. Click the Connect Now button, which will establish the serial connection<br />
and then automatically perform the same test as the Test Connection<br />
button. After a short delay, a Successfully connected message should<br />
appear next to the Test Connection button.<br />
d. You do not have to press the Download Core Application button because<br />
you will be downloading a different SALad application below.<br />
e. Click OK to close the Options window.<br />
4. Load the sample ‘Hello World’ SALad program.<br />
In the IDE, press the Open toolbutton (or else click the File->Open… menu item),<br />
then find and open HelloWorld1.sal in the Samples directory. A collection of files<br />
will appear in the editor window, with each file under a different tab. The tab<br />
labeled HelloWorld1 should automatically be selected after the files finish loading<br />
into the editor.<br />
October 14, 2005 © 2005 Smarthome Technology
5. Mark HelloWorld1 as the Main Code Module.<br />
Developer’s <strong>Guide</strong> Page 158<br />
Right-click on the HelloWorld1 tab and select Mark as Main Code Module. This<br />
tells the compiler which file contains the beginning of the SALad application<br />
program.<br />
6. View the ASCII Communications Window.<br />
Select the Comm Window tab at the bottom of the IDE in the Windows and<br />
Inspectors section.<br />
Under the Comm Window tab, select the ASCII Window tab to see text messages<br />
sent from the PLC to the PC.<br />
7. Compile and Download HelloWorld1.sal.<br />
In the IDE, press the Compile/Download toolbutton, or else click the Project-<br />
>Compile/Download menu item.<br />
The IDE’s LED will turn yellow and a progress bar will indicate that<br />
HelloWorld1.sal is being compiled and downloaded to the PLC. The IDE's LED will<br />
turn green when the download is completed.<br />
After the PLC receives the code, it will automatically reset and run the<br />
downloaded HelloWorld1.sal program from the beginning.<br />
The IDE’s ASCII Window will display the text:<br />
Database Initialized<br />
Core App Running<br />
Core App Running<br />
NOTE: If the PLC’s LED continues to flash on and off once per second after the<br />
download, the SALad program failed its checksum test. Recheck the serial<br />
connection and try the Compile/Download again.<br />
8. Test the HelloWorld1.sal program.<br />
Tap the PLC's SET Button (located above the LED) to fire the Button Tap SALad<br />
event. The HelloWorld1 SALad program will respond to the event by sending an<br />
ASCII message to the PC.<br />
The IDE’s ASCII Window will display the text:<br />
Core App Running-Button Pressed<br />
9. Debug the HelloWorld1.sal program.<br />
To the right of the toolbar, click the Debug Mode checkbox to begin a debugging<br />
session. A watch window will appear to the left of the editor pane. In debug<br />
mode, the PLC will report the address of its program counter to the IDE and<br />
optionally stop on each line, allowing you to debug the code.<br />
To try out the debugger, press the Fast Step toolbutton, and then tap the PLC's<br />
SET Button again. This time, the IDE will step rapidly through the program in the<br />
October 14, 2005 © 2005 Smarthome Technology
Developer’s <strong>Guide</strong> Page 159<br />
editor and highlight each line of code that it executes.<br />
You can cause the debugger to execute one line of code at a time by single<br />
stepping. Try pressing the Single Step toolbutton, and then tap the PLC’s SETt<br />
Button. The editor will highlight the first line of SALad code to be executed.<br />
Thereafter, each time you press the Single Step toolbutton, the highlighted line of<br />
code will execute, then the editor will jump to and highlight the next line to be<br />
executed after that one.<br />
You can set (soft) breakpoints in the code by clicking on the green dots in the<br />
margin at the left of the code. Active breakpoints are indicated by a red dot. To<br />
clear a breakpoint, just click it again.<br />
Try using a breakpoint by single-stepping a few lines into the code and setting a<br />
breakpoint there. Press the Fast Step toolbutton to let the code finish executing,<br />
and then press the PLC’s SET Button to fire a new event. The debugger will stop<br />
at the breakpoint you set.<br />
To run the debugger as fast as it will go, press the Run toolbutton. Soft<br />
breakpoints will be ignored but code highlighting will still work. If you don’t want<br />
the editor to jump around in the code as it executes, uncheck the Show CP check<br />
box (CP means Code Point).<br />
To exit the debugging session and allow the PLC to run normally, simply uncheck<br />
Debug Mode.<br />
10. Congratulations, you have compiled, downloaded, tested and debugged a<br />
sample SALad program running on a PowerLinc Controller.<br />
HelloWorld1.sal is built on a SALad coreApp Program called coreApp.sal that<br />
provides basic <strong>INSTEON</strong> and X10 communication along with other essential<br />
features such as initialization, serial communication, and timers. You can find<br />
other sample SALad programs and templates in the SALad IDE\Samples and<br />
SALad IDE\Code Templates directories.<br />
11. Further steps.<br />
You can become more familiar with <strong>INSTEON</strong> and X10 SALad programming by<br />
reading this Developer’s <strong>Guide</strong>, trying out other sample SALad programs, and<br />
using the debugger. Since SALad programs mostly consist of event handlers, the<br />
easiest and safest way to write SALad code is to modify existing code, such as<br />
coreUser.sal that already contains the necessary infrastructure.<br />
Smarthome and other leading developers are continuously creating new sample<br />
and real-world SALad applications. Be sure to check the <strong>INSTEON</strong> Forum<br />
frequently at http://www.insteon.net/sdk/forum/ for the latest information.<br />
October 14, 2005 © 2005 Smarthome Technology
IDE Main Window<br />
Developer’s <strong>Guide</strong> Page 160<br />
This is what the SALad IDE’s main window looks like. This section explains the IDE<br />
Menus and IDE Toolbar at the top.<br />
The IDE Editor is below the toolbar on the right. During debugging, the IDE Watch<br />
Panel appears to the left of the Editor. You can access the various IDE Windows and<br />
Inspectors at the bottom by clicking on the tabs.<br />
You can drag the borders at the left and bottom of the Editor to resize the panes,<br />
and you can instantly collapse or expand the Windows and Inspectors pane by<br />
clicking at the top of it.<br />
October 14, 2005 © 2005 Smarthome Technology
IDE Menus<br />
These are the main menus in the SALad IDE.<br />
In This Section<br />
Menu – File<br />
Opens and saves source and output files.<br />
Developer’s <strong>Guide</strong> Page 161<br />
Menu – Edit<br />
Helps you navigate within your source code, find text, replace found text, and<br />
modify IDE options.<br />
Menu – View<br />
Changes the appearance of the IDE by displaying and hiding various parts of it.<br />
Menu – Project<br />
Controls compilation options and loading of new firmware into the PLC.<br />
Menu – Mode<br />
Switches between using a real PLC, a simulated PLC, or no PLC.<br />
Menu – Virtual Devices<br />
Launches the virtual powerline and virtual LampLinc devices for use with the PLC<br />
Simulator.<br />
Menu – Help<br />
Launches this Developer’s <strong>Guide</strong> in compiled help form, gives version information<br />
about the IDE, lets you check for IDE updates, and links you to the <strong>INSTEON</strong><br />
Developer’s Forum.<br />
October 14, 2005 © 2005 Smarthome Technology
Menu – File<br />
Developer’s <strong>Guide</strong> Page 162<br />
The File menu is for opening and saving source and output files.<br />
or Toolbutton Creates a new source code<br />
file in the editor. A new blank file will appear under a new tab in the editor, labeled<br />
unnamedx, where x will increment as necessary to provide a unique filename. To<br />
save the new file under the name you really want it to have, use Save As….<br />
code file in the editor.<br />
or Toolbutton Opens an existing source<br />
This is the same as Open… except the submenu<br />
lets you choose from a list of the last files you opened.<br />
or Toolbutton (Keyboard Shortcut:<br />
Ctrl-S) Saves the file currently displayed in the editor using the same name as<br />
shown<br />
in the active tab (with an extension of sal), in the same directory from which<br />
it was opened.<br />
Saves the file currently displayed in the editor,<br />
using whatever name you choose, in whatever directory you choose.<br />
Saves all of the files under all tabs in the editor<br />
in the same way that an individual file would be saved.<br />
This compiles your SALad program and saves it<br />
as a binary file (with an extension of slb) in whatever directory and with whatever<br />
name you specify.<br />
This compiles your SALad program and saves it<br />
as a hexadecimal file (with an extension of hex) in whatever directory and with<br />
whatever name you specify.<br />
This is a very convenient option for saving your<br />
work<br />
and optionally sending it to someone else (or yourself). It will create a Zip file<br />
containing your source code, then launch your emailer with the Zip file already<br />
attached to a default message. If you don’t want to email the Zip file, just close the<br />
emailer.<br />
October 14, 2005 © 2005 Smarthome Technology
Developer’s <strong>Guide</strong> Page 163<br />
(Keyboard Shortcut: Ctrl-F4) Closes the file<br />
currently displayed in the editor. This will not delete the file saved on disk (if there<br />
is one).<br />
Closes all of the files currently open in the editor.<br />
This will not delete any of the files saved on disk<br />
(if they exist). After all of the files<br />
are<br />
closed, a new blank file will appear under a new tab in the editor, labeled<br />
unnamedx,<br />
where x will increment as necessary to provide a unique filename.<br />
Launches the Options dialog box, which lets you<br />
c hange various settings for the IDE. See IDE Options Dialog Box for details.<br />
This compiles your SALad program and saves it<br />
as<br />
a binary file (with an extension of slb) in whatever directory and with whatever<br />
name<br />
you specify.<br />
This saves the currently displayed source file in<br />
the<br />
editor as a listing file (with the extension txt). The listing includes the<br />
information<br />
in the ‘gutter’ at the left of the editor, which includes hex addresses,<br />
bytecode and line numbers.<br />
This ends your IDE session and closes the<br />
program. Be sure to save your work if you did not specify the Save all files on close<br />
option in the Options – Saving dialog box.<br />
October 14, 2005 © 2005 Smarthome Technology
Menu – Edit<br />
Developer’s <strong>Guide</strong> Page 164<br />
The Edit menu helps you navigate within your source code, find text, replace found<br />
text, and modify IDE options.<br />
(Keyboard Shortcut: Alt-G) This lets you jump<br />
to a specified line number in the source file currently displayed in the editor. The<br />
editor will display the line highlighted for a few seconds after it jumps to it. If you<br />
specify<br />
a line number beyond the end of the file, the editor will jump to the<br />
last line<br />
in the file.<br />
If this option is checked, you can edit source files.<br />
To<br />
disable editing, uncheck this option.<br />
Launches the Options dialog box, which lets you<br />
change various settings for the IDE. See IDE Options Dialog Box for details.<br />
or Toolbutton (Keyboard Shortcut: Alt-F)<br />
Launches the Find dialog box, which looks like this:<br />
You<br />
cse Ctrl-Down to find the next occurrence of the string you are finding, and<br />
Ctrl-Up to find the previous occurrence.<br />
or Toolbutton (Keyboard Shortcut: Alt-R)<br />
Launches the Find and Replace dialog box, which<br />
looks like this:<br />
October 14, 2005 © 2005 Smarthome Technology
Developer’s <strong>Guide</strong> Page 165<br />
You can use Ctrl-Down to find the next occurrence of the string you are finding, and<br />
Ctrl-Up to find the previous occurrence.<br />
October 14, 2005 © 2005 Smarthome Technology
Menu – View<br />
Developer’s <strong>Guide</strong> Page 166<br />
The View menu changes the appearance of the IDE by displaying and hiding various<br />
parts<br />
of it.<br />
Check or uncheck this option to display or hide the<br />
Windows and Inspectors tabs at the bottom of the IDE window. You can achieve<br />
the<br />
same result by clicking on the Windows<br />
and Inspectors label bar.<br />
This gives a submenu that changes the appearance of<br />
the information to the left of the source code in the editor. The submenu looks like<br />
this:<br />
You can check only one of the options. Full, the default, displays (from left to right)<br />
hex addresses,<br />
hex bytecode, source code line numbers, and breakpoint markers, as<br />
shown in the section IDE Editor,<br />
below. If you check Extended, the gutter pane is<br />
widened so you can see more of the bytecode. If you check any of the other<br />
options, so will only what you selected. During debugging, you will not be able to set<br />
breakpoints unless the Markers column is displayed.<br />
This launches the Startup Wizard that guides you<br />
through setting up communications with your PLC. You can achieve the same results<br />
manually by going to the Options – Communications menu.<br />
October 14, 2005 © 2005 Smarthome Technology
Menu<br />
– Project<br />
Developer’s <strong>Guide</strong> Page 167<br />
The Project menu controls compilat ion and loading of new firmware into the PLC.<br />
(Keyboard Shortcut: F9 while not debugging)<br />
This compiles your SALad program and downloads<br />
the compiled bytecode to your<br />
PLC (which can be a real PLC or the PLC Simulator). The Compile/Download<br />
toolbar button does the same thing.<br />
This lets you download a selected version of firmware<br />
code to the PLC. Firmware object code has the file extension ump.<br />
Menu – Mode<br />
The Mode menu switches between using a real PLC, a simulated PLC, or no PLC. You<br />
can select only one of the options.<br />
option is the default.<br />
Select this option if you are connected to a real PLC. This<br />
Select this option if you are not connected to a PLC. You<br />
will not be able to download or debug code while you are offline.<br />
Select this option if you wish to use the software PLC<br />
Simulator. You can download code to the PLC Simulator and debug it just as you<br />
would for a real PLC. See the<br />
October 14, 2005 © 2005 Smarthome Technology
Developer’s <strong>Guide</strong> Page 168<br />
PLC Simulator section below for more information.<br />
While you are using the PLC<br />
Simulator you can also simulate a Virtual<br />
Powerline environment along with any<br />
number of Virtual LampLinc devices plugged into it.<br />
October 14, 2005 © 2005 Smarthome Technology
Menu – Virtual Devices<br />
Developer’s <strong>Guide</strong> Page 169<br />
The Virtual Devices menu launches the virtual powerline and virtual LampLinc<br />
devices for use with the PLC Simulator.<br />
This will launch a virtual LampLinc device simulated in<br />
software. The virtual LampLinc will appear in a separate window. See Virtua l<br />
LampLinc for details.<br />
This will launch a virtual powerline environment simulated in<br />
software.<br />
The virtual powerline will appear in a separate window. If you are going<br />
to use the virtual LampLinc, launch a virtual powerline first. See Virtual Powerline<br />
for details.<br />
October 14, 2005 © 2005 Smarthome Technology
Menu – Help<br />
Developer’s <strong>Guide</strong> Page 170<br />
The Help menu launches this Developer’s <strong>Guide</strong><br />
in compiled help form, gives version<br />
information about the IDE, lets you check for IDE updates, and links you to the<br />
<strong>INSTEON</strong> Developer’s Forum.<br />
Developer’s <strong>Guide</strong> in compiled help format.<br />
This<br />
launches this <strong>INSTEON</strong><br />
This displays a screen like this one:<br />
This will automatically check for<br />
newer versions of the IDE and update it if appropriate.<br />
take you to www.insteon.net.<br />
This will open your web browser and<br />
October 14, 2005 © 2005 Smarthome Technology
IDE Toolbar<br />
This is what the main Toolbar looks like:<br />
This is what the individual toolbuttons do:<br />
Connect or Reconnect serially to the PLC.<br />
New File. Create a new SALad file (*.sal).<br />
Developer’s <strong>Guide</strong> Page 171<br />
Open File. Open a SALad file (*.sal) or SALad Template (*.salt).<br />
Save File. Save the current SALad file (*.sal) or SALad Template (*.salt).<br />
Reset. Reset the PLC by forcing an EVNT_INIT (0x00) IBIOS Event (see<br />
IBIOS Event Details, Note 1). This will start the SALad program with EVNT_INIT<br />
( 0x00) in its event queue.<br />
Stop. Stop execution of the SALad program.<br />
Pause. During debugging only, pause the SALad program at the next line of<br />
code.<br />
Single Step. During debugging only, execute the next line of code in the<br />
SALad program. This line is normally highlighted in the IDE.<br />
Fast Step to Next Breakpoint. During debugging only, execute one line of<br />
code at a time, reporting each line executed, and stop at the next soft or hard<br />
breakpoint.<br />
Run in Animate Mode. During debugging, run at top debugging speed,<br />
reporting each line executed, and stop at the next soft or hard breakpoint or at the<br />
end of the program. During normal execution, run at full speed and stop at the next<br />
hard breakpoint or at the end of the program.<br />
Find. Find text in the currently displayed SALad program.<br />
Find and Replace. Find and replace text in the currently displayed SALad<br />
program.<br />
Compile and Download. Compile the SALad program and download the<br />
bytecode into the PLC over the serial port. If you right-click this button, the<br />
following options appear:<br />
1. Display differences between the<br />
code to download and the code read back from the PLC.<br />
October 14, 2005 © 2005 Smarthome Technology
Developer’s <strong>Guide</strong> Page 172<br />
2. Download all files on the next<br />
download instead of just incrementally downloading files that have changed.<br />
3. Always download all files. This is<br />
the default setting.<br />
4. Read back the code image from<br />
the PLC after the next code download.<br />
LED. This is an indicator only, not a button. After pressing the<br />
Connect/Reconnect button, green means you are successfully connected to the PLC<br />
and red means you are not connected. After pressing the Compile/Download<br />
button, green means the program downloaded to the PLC successfully, red means<br />
the program did not download successfully, and yellow means the program is<br />
currently downloading.<br />
Go Back. Return to the previous SALad program location in the editor. Use<br />
this after hot-jumping to another SALad program by right-clicking on a label.<br />
There are two checkboxes, used for debugging:<br />
Enable/Disable Debugging Mode. When checked, you will be in<br />
debugging mode and the Watch window will appear to the left of the edit window.<br />
You can change the size of the Watch window by dragging the separator bar.<br />
Show Code Point. When you are debugging and Show CP is<br />
checked, the editor will jump to whatever code line is executing and highlight that<br />
line, even if the line is not on the currently displayed page. When Show CP is<br />
unchecked, the currently displayed page will remain visible during execution.<br />
The pulldown box works with the editor:<br />
Jump To Label. This pulldown box<br />
contains all labels used in the SALad program. When you select a label from the<br />
pulldown box, the editor will jump to the program location where the label first<br />
appears. During editing and debugging, the label displayed in the pulldown box will<br />
be the one that fits the current context.<br />
October 14, 2005 © 2005 Smarthome Technology
IDE Editor<br />
Developer’s <strong>Guide</strong> Page 173<br />
The<br />
IDE editor handles multiple source files and displays SALad source code in<br />
context-sensitive color. The screenshot below shows how an editing session would<br />
typically<br />
appear.<br />
SALad program files (e.g. core1x.sal, base.sal, cmds.sal)<br />
Compiled SALad bytecode<br />
Hexadecimal address of executable code<br />
Next line to execute highlighted during debugging<br />
Labels, definitions, declarations start at column 1<br />
Breakpoint marker (<br />
Source code line numbers<br />
SALad program code<br />
), executable marker ( )<br />
You can change the appearance of the editor by right-clicking anywhere in the editor<br />
pane and selecting Editor Properties…. This displays<br />
the Editor tab in the Options<br />
dialog box. See the Options – Editor section for details.<br />
You can change which columns of information are displayed in the ‘gutter’ using the<br />
V iew->Gutter menu item (see Menu – View above).<br />
October 14, 2005 © 2005 Smarthome Technology
Developer’s <strong>Guide</strong> Page 174<br />
Right-clicking anywhere in the editor displays the following menu options:<br />
copies selected text to the clipboard.<br />
cuts selected text to the clipboard.<br />
(Keyboard Shortcut: Ctrl-C) This<br />
(Keyboard Shortcut: Ctrl-X) This<br />
(Keyboard Shortcut: Ctrl-V) This<br />
Pastes text in the clipboard at the cursor location.<br />
selects all of the text in the current file.<br />
(Keyboard Shortcut: Ctrl-A) This<br />
This sets the program counter so<br />
that the next line to be executed will be where the cursor is, i.e. where you rightclicked<br />
to get this popup menu.<br />
This sets the program counter so<br />
that the next line to be executed will be where the caret is. The caret (a vertical<br />
bar) is where you last left-clicked clicked with the cursor.<br />
Run the program from the Code<br />
Point (the current address of the program counter) to the line where the cursor is,<br />
i.e. where you right-clicked to get this popup menu.<br />
Run the program from the Code<br />
Point (the current address of the program counter) to the line where the caret is.<br />
The caret (a vertical bar) is where you last left-clicked clicked with the cursor.<br />
Add the variable under the caret to<br />
the Watch Window. The caret (a vertical bar) is where you last left-clicked clicked<br />
with the cursor. See IDE Watch Panel for details.<br />
October 14, 2005 © 2005 Smarthome Technology
Developer’s <strong>Guide</strong> Page 175<br />
If there are any undefined labels in<br />
your SALad program, this will insert them at the cursor position so you can define<br />
them.<br />
This displays the Editor tab in the<br />
Options dialog box, so you can change the way the editor looks and behaves. See<br />
Options – Editor for details.<br />
October 14, 2005 © 2005 Smarthome Technology
IDE Watch Panel<br />
Developer’s <strong>Guide</strong> Page 176<br />
The watch panel appears to the left of the editor during debugging sessions. You can<br />
change its size by dragging the border between it and the editor.<br />
Reread and redisplay all memory watches<br />
Automatically reread and redisplay<br />
upon each Single Step (for debugging)<br />
A single watch line:<br />
NTL_EVENT (8 bits) is at address 0x0036,<br />
which held 0xFF when last<br />
read<br />
Font size for<br />
display<br />
Address is that of a pointer to the watched address<br />
You can add variables that you want to watch by clicking on a variable in the editor,<br />
then right-clicking and choosing Add Watch in the popup menu.<br />
Click the Refresh Page button to update all<br />
watches. If the Auto-Refresh on<br />
SingleStep check box is checked, then single<br />
stepping during debugging (keyboard<br />
shortcut F8) will update the watches after each step.<br />
Check Indirect if the variable that you are watching<br />
contains a pointer to another<br />
variable. The Watch Window will display then also display the contents of the<br />
variable being pointed to.<br />
The<br />
pulldown box lets you choose whether the watched address is the beginning of<br />
an 8-bit variable, a 16-bit variable, an ASCII string, or a hex string. If it is an ASCII<br />
or hex string, set the length of the string to display in the Len: box.<br />
October 14, 2005 © 2005 Smarthome Technology
IDE Options Dialog Box<br />
Developer’s <strong>Guide</strong> Page 177<br />
The Options Dialog Box has a number of tabs that<br />
look like this. The panels that the<br />
various<br />
tabs display are explained below. You can launch the Options Dialog Box by<br />
choosing<br />
the Edit->Applications Options… menu item.<br />
The OK and Cancel buttons appear at the bottom of each panel, but they are not<br />
shown in the figures below. Settings take effect when you push OK. If you push<br />
Cancel the previous settings will remain in effect.<br />
In This Section<br />
Options – General<br />
Controls overall IDE behavior.<br />
Options – Quick Tools<br />
A set of tools for working with the PLC’s firmware and Link Database.<br />
Options – Debugging<br />
Contains controls for debugging sessions.<br />
O ptions – Compiling<br />
Contains controls for the compiler.<br />
Options – Communications<br />
Has setup options and tools to control communication with the PLC.<br />
Options – Unit Defaults<br />
Controls settings for the PLC firmware.<br />
Options – Directories<br />
Sets file search paths.<br />
Options – Editor<br />
Controls how the editor looks and behaves.<br />
Options – Saving<br />
Sets file saving and backup options.<br />
Options – Loading<br />
Sets file loading options.<br />
Options – Project<br />
Designates the file containing the beginning of your SALad program.<br />
October 14, 2005 © 2005 Smarthome Technology
Options – General<br />
The General tab controls overall IDE behavior.<br />
Developer’s <strong>Guide</strong> Page 178<br />
Currently the only option is to show the Splash Screen when the program starts.<br />
This defaults to off after the first time the program is run.<br />
Options – Quick Tools<br />
Quick Tools are for working with the PLC’s firmware and Link Database. These are<br />
here for convenience and others may be added in the future.<br />
Convert INC into UMP and Convert INC into SAL are utilities for converting assembler<br />
include (INC) files into Unit Map files (UMP) or SALad source code files (SAL).<br />
Zero Database (FC00-FFFF) clears the PLC Link Database from hex address 0xFC00<br />
to 0xFFFF by writing zeros into it. You can also zero the Link Database from the<br />
October 14, 2005 © 2005 Smarthome Technology
PLC Database tab under Windows and Inspectors.<br />
Developer’s <strong>Guide</strong> Page 179<br />
October 14, 2005 © 2005 Smarthome Technology
Options – Debugging<br />
Developer’s <strong>Guide</strong> Page 180<br />
The Debugging tab contains controls for debugging sessions.<br />
Auto-disconnect device after 5 consecutive access violations stops serial data flow if<br />
faulty SALad code is generating an access violation storm that prevents you from<br />
seeing where the code went awry.<br />
Log<br />
all raw data into lets you designate a text file that will log<br />
the data that appears in the<br />
October 14, 2005 © 2005 Smarthome Technology
Comm Window – Raw Data panel.<br />
Options – Compiling<br />
The<br />
Compiling tab contains controls for the compiler.<br />
Developer’s <strong>Guide</strong> Page 181<br />
Prevent download when errors exist, when checked, will not download bytecode to<br />
the PLC if the compiler generates errors. This option is checked by default.<br />
October 14, 2005 © 2005 Smarthome Technology
Options – Communications<br />
Developer’s <strong>Guide</strong> Page 182<br />
The Communications tab has setup options and tools to control<br />
communication with<br />
the<br />
PLC.<br />
Press Find my PowerLinc Controller to check your serial ports for an attached PLC. If<br />
a PLC is found, the port to which it is attached will appear in the Port: pulldown box.<br />
If you want to manually designate the serial port that your PLC is attached to, you<br />
can use the pulldown box directly. The pulldown box contains options for your<br />
available COM (RS232) and USB ports. If you are using the PLC Simulator it does<br />
not matter which option you choose.<br />
Press the Connect Now button to establish a connection with your PLC over the port<br />
designated in the Port: pulldown box. Pushing the Connect Now button will<br />
automatically “push” the Test Connection button.<br />
If you are already connected to your PLC, you can test the connection at any time by<br />
pressing the Test Connection button.<br />
Press Download Core Application to download a precompiled version of the<br />
coreApp.sal SALad coreApp Program to your PLC. This file to be downloaded, named<br />
coreApp.slb, is the one in the Program Files\Smarthome\Salad IDE\core directory.<br />
Press Advanced Commands… to toggle the appearance of a pulldown box containing<br />
PLC command options that only apply to particular versions of the PLC. The<br />
command shown, Set Daughterboard Monitoring OFF is for a Hardware Development<br />
Kit. Press the Send button to actually send the chosen command to the PLC<br />
October 14, 2005 © 2005 Smarthome Technology
Options – Unit Defaults<br />
Developer’s <strong>Guide</strong> Page 183<br />
The Unit Defaults tab controls settings for the PLC firmware.<br />
Image Base: is the base address for the downloaded compiled SALad bytecode. This<br />
should match the ‘org’ of the first executable code in the file you designate as ‘main’<br />
in the Options – Project tab. The default is 0x0210.<br />
Map File: lets you designate a unit map (UMP) file other than the one that the IDE<br />
defaults to by auto-sensing which firmware version is running in your PLC.<br />
Options – Directories<br />
The Directories tab sets file search paths.<br />
Enter the path to files that you would like the IDE to search for to be included in your<br />
project. Press the button to open a standard dialog box to find a directory. If you<br />
want multiple search paths, separate them with a semicolon. The default search<br />
paths are your current project’s directory ( usually under Smarthome\SALad<br />
IDE\Projects), then the Smarthome\SALad IDE\Include directory, then the<br />
Smarthome\SALad IDE\Core directory.<br />
October 14, 2005 © 2005 Smarthome Technology
Options<br />
– Editor<br />
Developer’s <strong>Guide</strong> Page 184<br />
The Editor tab controls how the<br />
editor looks and behaves. You can also launch this<br />
page directly from the editor by right-clicking anywhere in it and choosing Editor<br />
Properties….<br />
Use the Theme: pulldown box to select a previously saved collection of the color and<br />
font settings on this page. The default theme is called standard. You can create<br />
custom themes by choosing the editor options you want on this page and then<br />
pressing Save Current Theme… to store the settings under a name you choose.<br />
Whenever you launch the IDE, the editor will use the theme that last appeared in the<br />
pulldown box.<br />
To change the foreground or background color for text of a given type, click on the<br />
color box and choose the color you want.<br />
Check the BOLD box if you want text of the given type to appear bold, and check the<br />
Use BG box if you want the specified background color to actually be used.<br />
Use the Editor Font: pulldown box to choose the font for the editor.<br />
Check Show Code Hints if you want tooltips to appear as you type SALad<br />
instructions. The tooltips show the parameters for the instruction and a brief<br />
description of what it does.<br />
Check Allow (ctrl-space) Code Completion Window if you want to see possible SALad<br />
word completions by pressing Control-Space after you’ve typed a partial word.<br />
Check Smart Tabs if you want the editor to automatically indent or outdent the next<br />
line, depending on context, when you press Enter at the end of a code line.<br />
October 14, 2005 © 2005 Smarthome Technology
Developer’s <strong>Guide</strong> Page 185<br />
Set the number of spaces for a tab in the Tab Size: box. The default is 3. Tabs are<br />
converted to spaces in saved files.<br />
Options – Saving<br />
The Saving tab sets file saving and backup options.<br />
Check Save all files on close if you want the IDE to automatically save all open<br />
source code files when you close the IDE. The files will be saved in whatever<br />
condition they are in at the time, so be careful when using this option. The default is<br />
unchecked.<br />
Check Save all files on IDE errors if you want the IDE to automatically save all open<br />
source code files whenever an error occurs in the IDE program. Then, if the IDE<br />
crashes, when you restart it you will get a dialog box informing you that your files<br />
were auto-recovered from backups, and giving you the option of keeping the autorecovered<br />
files or not. The default for this option is checked.<br />
Check<br />
Backup files on load up to N levels if you want the IDE to automatically save<br />
source<br />
code files with a bak extension whenever they are loaded. If you set the<br />
number of levels greater than 1 (the default is 5), then bak files are first renamed<br />
with an extension bk1, bk1 files are renamed bk2, and so forth. This option is<br />
checked by default. NOTE: This option has not been implemented as of version<br />
1.0.5.170 of the IDE.<br />
Check Save all on download if you want the IDE to automatically save all open<br />
source code files whenever you download compiled code to your PLC program. The<br />
default is checked.<br />
October 14, 2005 © 2005 Smarthome Technology
Options – Loading<br />
The Loading tab sets file loading options.<br />
Developer’s <strong>Guide</strong> Page 186<br />
Check Automatically load all included files if you want the IDE to find and load any<br />
files that you have named in a source file using an include ""<br />
statement. The default is checked.<br />
Options – Project<br />
The Project tab lets you designate the file containing the beginning of your SALad<br />
program. If you do not do this, the compiler will not know where program execution<br />
begins. This setting is persistent, meaning that the IDE will remember it between<br />
sessions.<br />
You can either type the name of the file in the text box, or you can right-click on the<br />
file’s tab in the editor and choose Mark as main unit.<br />
October 14, 2005 © 2005 Smarthome Technology
IDE Windows and Inspectors<br />
Developer’s <strong>Guide</strong> Page 187<br />
Windows and Inspectors is a collection of tools that you will find very useful when<br />
using the IDE to create <strong>INSTEON</strong> applications using SALad. The main tools appear<br />
under a set of tabs that look like this:<br />
Choosing Comm Window will display a series of subtabs with more tools.<br />
You<br />
can make the Windows and Inspectors pane collapse or expand quickly by<br />
clicking anywhere in its title bar. You can resize the pane by dragging its top border.<br />
In This Section<br />
Compile Errors<br />
Lists errors the compiler finds and lets you jump to them in the editor for<br />
debugging.<br />
Comm Window<br />
Has a collection of subtabs that help you to see what is going on in the <strong>INSTEON</strong><br />
environment.<br />
Trace<br />
Lets you inspect the execution history of your program to help you with<br />
debugging.<br />
PLC Database<br />
A tool for manipulating the Link Database in your PLC.<br />
SIM Control<br />
Operates the PLC Simulator.<br />
October 14, 2005 © 2005 Smarthome Technology
Compile Errors<br />
Developer’s <strong>Guide</strong> Page 188<br />
This page shows errors that the compiler finds. Each line displays an error number,<br />
the<br />
filespec of the file containing the error, the line number and column positions of<br />
the<br />
error within the file, and an error message. Double-clicking an error places you<br />
on the<br />
offending line in the editor.<br />
In the example above, an error was deliberately induced by changing a valid label<br />
(tjump) to an invalid one (tjump foo).<br />
Double-clicking on one of the lines above<br />
shows<br />
the error in the editor like this:<br />
October 14, 2005 © 2005 Smarthome Technology
Comm Window<br />
Developer’s <strong>Guide</strong> Page 189<br />
The Comm Window has a number of sub-tabs that look like this:<br />
In This Section<br />
Comm Window – Raw Data<br />
Shows the serial data exchanged between the PLC and your PC.<br />
Comm Window – PLC Events<br />
Displays PLC Events that have occurred.<br />
C omm Window – <strong>INSTEON</strong> Messages<br />
Displays received <strong>INSTEON</strong> messages, and<br />
it lets you compose and send<br />
<strong>INSTEON</strong> messages of your choosing.<br />
Comm Window – X10 Messages<br />
Displays received X10 commands, and it lets you compose and send X10<br />
commands of your choosing.<br />
Comm Window – Conversation<br />
Allows you to have a two-way serial conversation with<br />
the PLC.<br />
Comm Window – ASCII Window<br />
Displays text explicitly sent from a SALad 2 program<br />
running on your PLC.<br />
Comm Window – Debug Window<br />
Lets you directly inspect and alter bytes within your PLC.<br />
Comm Window – Date/Time<br />
Gives you control over the realtime clock in the PLC and lets you test realtime<br />
events.<br />
October 14, 2005 © 2005 Smarthome Technology
Comm Window – Raw Data<br />
Developer’s <strong>Guide</strong> Page 190<br />
The Raw Data page shows the serial data exchanged between your PLC and your PC.<br />
The data is displayed as hexadecimal bytes.<br />
A T: precedes data transmitted from the PC to the PLC.<br />
An S: precedes data transmitted from the PC to the PLC, but with any packet<br />
formatting that may have been applied also displayed. In particular, USB<br />
communications adds formatting as described in the section IBIOS USB Serial<br />
Interface above.<br />
An R: precedes data received by the PC from the PLC.<br />
Comm Window – PLC Events<br />
SALad is event-driven, meaning that SALad programs respond to events that occur<br />
in the host environment. This page displays IBIOS Events that have occurred in the<br />
PLC. See IBIOS Events for a list of events that SALad handles.<br />
The left column displays the event number in hexadecimal, followed by the event<br />
name and a description of the conditions that caused the event.<br />
October 14, 2005 © 2005 Smarthome Technology
Developer’s <strong>Guide</strong> Page 191<br />
October 14, 2005 © 2005 Smarthome Technology
Developer’s <strong>Guide</strong> Page 192<br />
Comm Window – <strong>INSTEON</strong> Messages<br />
The <strong>INSTEON</strong> Messages page displays received <strong>INSTEON</strong> messages, and it lets you<br />
compose<br />
and send <strong>INSTEON</strong> messages of your choosing.<br />
The top section of this page displays <strong>INSTEON</strong> messages received by the PLC. See<br />
Message Fields above for a description of the column headings.<br />
The<br />
bottom section lets you compose and send an <strong>INSTEON</strong> message. You can<br />
choose from a number of pre-composed commands using the pulldown box at the<br />
left.<br />
You can enter From and To Device Addresses in the text boxes by typing the 3-byte<br />
address as three decimal numbers separated by periods.<br />
This is similar to the way<br />
an IP address is specified on the Internet.<br />
You can set the Message Type Flags the message using the check boxes.<br />
Use the RemHops and TotHops boxes to set the Message Retransmission Flags.<br />
Enter the Command 1 and 2 that you want to send as hexadecimal bytes in the<br />
respective boxes.<br />
If you are sending an Extended Message, enter the User Data in the Extended Data<br />
text box. If you enter any data in this box, an Extended Message will be sent. If<br />
you enter more than 14 bytes, only the first 14 bytes will be sent. If you enter fewer<br />
than 14 bytes, the remaining bytes will be sent as 0x00. If you want to send a<br />
Standard<br />
Message, clear this box.<br />
You do not have to deal with the Message Integrity Byte (CRC) because the <strong>INSTEON</strong><br />
Engine handles this for you.<br />
When you have composed the <strong>INSTEON</strong> message that you want, press the Send<br />
<strong>INSTEON</strong> button to transmit it.<br />
October 14, 2005 © 2005 Smarthome Technology
Comm Window – X10 Messages<br />
Developer’s <strong>Guide</strong> Page 193<br />
The X10 Messages page displays received X10 commands, and it lets you compose<br />
and send X10 commands of your choosing.<br />
The text box displays X10 traffic.<br />
A T: precedes X10 commands transmitted by the PLC.<br />
An R: precedes X10 commands received by the PLC.<br />
To compose an X10 command, choose its two bytes from the pulldown boxes, then<br />
press the Send button.<br />
October 14, 2005 © 2005 Smarthome Technology
Comm Window – Conversation<br />
Developer’s <strong>Guide</strong> Page 194<br />
The Conversation page allows you to have a two-way serial dialog with the PLC.<br />
The text box displays the conversation in hexadecimal bytes.<br />
A T: precedes hex bytes transmitted to the PLC.<br />
An R: precedes hex bytes received from the PLC.<br />
The yellow text box at the bottom allows you to type in hex bytes to send to the PLC.<br />
The pulldown<br />
holds the history of your sent bytes.<br />
Press the Send button to transmit the bytes displayed in the yellow text box.<br />
If you would like to send an entire hex file to the PLC, press the Send Hex File…<br />
button<br />
to choose and send the file. The hex file must be a text file containing 2character<br />
ASCII hex bytes separated by spaces or newlines, such as the files<br />
produced by the compiler under the Files->Save Hex Values As… menu item.<br />
The Firmware button sends 0x02 0x48, which requests the PLC’s firmware revision.<br />
This is a convenient way to determine if a PLC is connected and listening.<br />
October 14, 2005 © 2005 Smarthome Technology
Comm Window – ASCII Window<br />
Developer’s <strong>Guide</strong> Page 195<br />
The ASCII Window displays text explicitly sent from a SALad 2 program running on<br />
your PLC.<br />
Use the SerialSendBuffer command within<br />
a SALad program to generate messages<br />
that will be displayed in this text box.<br />
October 14, 2005 © 2005 Smarthome Technology
Comm Window – Debug Window<br />
Developer’s <strong>Guide</strong> Page 196<br />
The Debug Window lets you directly inspect and alter bytes within your PLC.<br />
Enter plc in the Unit ID: box to inspect (peek) and write to (poke) bytes in your PLC.<br />
If you want to peek and poke bytes in a remote <strong>INSTEON</strong> device, enter that device’s<br />
<strong>INSTEON</strong> Address as, for example, 1.2.3.<br />
Type the hex address you wish to inspect or write to in the Address: box. Press Get<br />
Byte to fetch a single hex byte at that address and display it in the Value: box, or<br />
else press Get Block to fetch a string of 32 hex bytes and display them all in the<br />
lower box.<br />
To poke a byte, type the hex byte you wish to poke at the given Address: in the<br />
Value:<br />
box, then press Set Byte.<br />
October 14, 2005 © 2005 Smarthome Technology
Comm Window – Date/Time<br />
Developer’s <strong>Guide</strong> Page 197<br />
The Date/Time page gives you control over the realtime clock (RTC) in the PLC and<br />
lets y ou test realtime events. All times are in 24-hour ‘military’<br />
format.<br />
The System Time box displays the time according to your PC, and the PLC Time box<br />
displays the time according to your PLC.<br />
To synchronize your PLC to your PC, press the Set-> button. The time in the PLC<br />
Time box will update to the system time.<br />
To set the PLC’s RTC to an arbitrary date/time, enter the date and<br />
time you wish to<br />
set in the boxes above the Set Date/Time of PLC button, then press that button. The<br />
time in the PLC Time box will update within the next minute. To quickly<br />
restore the<br />
date and time boxes to the current PLC time, press the Restore Date/Time Now<br />
button.<br />
Press the Test Set to Near Midnight button to set the PLC’s time to 23:59:45 so you<br />
can test functions that occur at midnight.<br />
Press the Clear RTC PowerOff button if you do not want the PLC’s RTC to save the<br />
current time if the PLC loses power.<br />
If you want to test timers that depend on the PLC’s minutes-from-midnight counter<br />
(see IBIOS Event Details Note 8), you can set the counter by entering a value from 0<br />
to 1439 in the Min from Mid (Minutes from Midnight) box and pressing the Set button<br />
to the<br />
right.<br />
Enter a minutes-from-midnight value from 0 to 1439 in the Next<br />
Alarm box and<br />
press the Set button to the right to cause an EVNT_ALARM (0x0E) IBIOS Event to<br />
fire when the PLC’s minutes-from-midnight value matches the value you entered.<br />
See IBIOS Event Details Note 8 for more information.<br />
Press the Calc Sunset/Sunrise >>> button to fill in the boxes to the right with the<br />
sunrise and sunset times for the PLC date. The box to the right gives the hourdifference<br />
between the local time zone and GMT (Greenwich Mean Time).<br />
October 14, 2005 © 2005 Smarthome Technology
Trace<br />
Developer’s <strong>Guide</strong> Page 198<br />
The Trace page lets you inspect the execution history of your program to help you<br />
with debugging.<br />
Tracing is active whenever you are in Debug mode (i.e. the Debug Mode checkbox is<br />
checked).<br />
The first column gives the hexadecimal address of the object code that was<br />
executed.<br />
The second column gives the line number and the source code filename of the line of<br />
code that was executed.<br />
The rightmost column shows the program statement that was executed.<br />
October 14, 2005 © 2005 Smarthome Technology
PLC Database<br />
Developer’s <strong>Guide</strong> Page 199<br />
The PLC Database page is a tool for manipulating the Link Database in your PLC.<br />
S ee <strong>INSTEON</strong> Link Database above for more information.<br />
To examine the contents of the PLC’s Link Database, press Read Database. The<br />
contents will appear in the text box at the right. If the text box is blank, the Link<br />
Database is zeroed out.<br />
To erase the Link Database by zeroing it out, press the Zero DB (FC00-FFFF) button.<br />
Zeros will be written to addresses 0xfc00 to 0xffff in the PLC’s EEPROM (nonvolatile<br />
memory).<br />
To add an entry to the Link Database, type the <strong>INSTEON</strong> Address of the device you<br />
wish to add in the ID: box, and the number of the Group you would like the device to<br />
belong to in the Group: box, and then press the Add to PLC Database button. When<br />
you enter the 3-byte <strong>INSTEON</strong> Address, type it as three decimal numbers, ranging<br />
from 0 to 255, separated<br />
by periods (for example: 126.23.4).<br />
To remove an entry from the Link Database, put the entry’s ID and Group number in<br />
the appropriate<br />
boxes, and then press Remove from PLC Database.<br />
After zeroing the Link Database or adding or removing a Link Database entry, you<br />
can press the Read Database button to see the effect of the change.<br />
If you double-click on a line in the text box, the IDE will jump to the C omm Window<br />
– Debug Window and display a hex dump of the bytes in the Link Database starting<br />
at<br />
the address of the entry you double-clicked on.<br />
As an example, if you press the Zero DB (FC00-FFFF) button, enter an ID of 2.3.4<br />
and a Group of 1, press the Add to PLC Database button, and finally press the Read<br />
Database button, the following line will appear in the text box:<br />
(id=02.03.04,mode=sla,addr=FFE8,laddr=0000,g=1,cmds=00 00,d=00)<br />
See PLC Link Database above for the meaning of these fields.<br />
October 14, 2005 © 2005 Smarthome Technology
SIM Control<br />
Developer’s <strong>Guide</strong> Page 200<br />
The SIM Control window operates the PLC Simulator. To use the PLC Simulator in<br />
place<br />
of a real PLC, turn it on by choosing the Mode->Simulator menu item (see<br />
M enu – Mode).<br />
The PLC Simulator Control Panel is at the upper left. The text box at the upper right<br />
is a hex PLC Simulator Memory Dump, and the text box at the bottom is a PLC<br />
Simulator Trace of code execution. You can vary the size of the Trace box by<br />
dragging its top border.<br />
In This Section<br />
PLC Simulator Control Panel<br />
Explains the controls at the top of the window.<br />
PLC Simulator Memory Dump<br />
Shows how to view memory in the PLC Simulator.<br />
PLC Simulator Trace<br />
Describes the trace information in the bottom text box.<br />
October 14, 2005 © 2005 Smarthome Technology
PLC Simulator Control Panel<br />
Developer’s <strong>Guide</strong> Page 201<br />
This is what the PLC Simulator Control Panel section looks<br />
like:<br />
A simulated SET Button (which you can press) and a simulated white Status LED<br />
(which you can view) appear at the left.<br />
You can simulate unplugging and plugging in the PLC using the Plugged In checkbox.<br />
If you would like to simulate a factory reset, uncheck Plugged In, check Factory<br />
Reset, then check Plugged In.<br />
Check Overclock to run the simulated PLC’s realtime clock at<br />
very high speed<br />
between events. This lets you easily test code that depends on realtime events<br />
without waiting for the actual time to elapse or manually resetting the<br />
PLC’s clock to<br />
fire an event.<br />
Use the Speed control at the far right to slow down simulated execution speed. This<br />
can be useful for debugging.<br />
If you are simulating a PLC with a Hardware Development Kit (HDK) added, choose<br />
the HDK from the Supplemental Sims:<br />
pulldown box.<br />
You can cause the PLC Simulator to execute a string<br />
of ASCII text commands from a<br />
macro file by typing the filespec for the macro file in the text box to the left of the<br />
Execute button, then pressing the button. Contact info@insteon.net for the format<br />
for the macro file.<br />
To poke a byte or bytes into the PLC Simulator’s memory, enter the hex address to<br />
poke to, and the hex byte(s) you want to poke, in the text boxes to the left of the<br />
Poke button, and then press the button. If you are poking multiple bytes, separate<br />
them with spaces.<br />
To simulate the occurrence of an IBIOS Event, enter the Event Handle number (see<br />
IBIOS Events) in the text box to the left of the Event button, then press the button.<br />
Check the Show Output checkbox if you want the PLC Simulator Trace to display<br />
code execution<br />
information.<br />
Push the Erase button<br />
to blank the PLC Simulator Trace text box.<br />
October 14, 2005 © 2005 Smarthome Technology
PLC Simulator Memory Dump<br />
Developer’s <strong>Guide</strong> Page 202<br />
This is what the PLC Simulator Memory Dump section looks like:<br />
To view memory contents in the PLC Simulator, enter a hex address, a range of<br />
addresses, or some combination of addresses and ranges in the Memory Map View:<br />
text box. The text box will immediately display the memory contents you specified.<br />
Indicate an address range by typing a beginning<br />
and ending address separated by a<br />
hyphen. Use a comma to separate multiple addresses or address ranges.<br />
The memory dump normally refreshes automatically every few milliseconds. If for<br />
some reason refreshing stops (if you switch serial ports, for instance), you can<br />
restart it by typing<br />
anything in the Memory Map View: box.<br />
October 14, 2005 © 2005 Smarthome Technology
PLC Simulator Trace<br />
This is what the PLC Simulator Trace section looks like:<br />
Drag the border at the top to resize the text box.<br />
Developer’s <strong>Guide</strong> Page 203<br />
Push the Erase button in the PLC Simulator Control Panel to blank the text box.<br />
Check the Show Output checkbox in the PLC Simulator Control Panel if you want the<br />
text box to display code execution information.<br />
When Show Output is checked, trace information like that shown above with an<br />
asterisk at the left will appear. Immediately following the asterisk is the hex address<br />
of the code line that was executed, followed by the object code itself. Effects that<br />
the code may have are shown to the right. For example,<br />
0676:00->FF<br />
means that memory location 0676 was changed from containing 00 to containing FF;<br />
and<br />
(comp=)0000
IDE Virtual Devices<br />
Developer’s <strong>Guide</strong> Page 204<br />
The Virtual Devices included in the SALad IDE allow you to develop SALad<br />
applications without being connected to any external hardware—in other words, you<br />
don’t need a connection to a real PowerLinc V2 Controller (PLC).<br />
The key tool is the PLC Simulator, which is a pure-software version of a real PLC<br />
running on your PC. The PLC Simulator can do everything that a real PLC can do,<br />
but it is more transparent, thanks to the special tools in the SIM Control window.<br />
W hen you are using the PLC Simulator, you can also simulate a Virtual Powerline<br />
e nvironment in software. Then, you can plug in any number of Virtual LampLinc<br />
devices to the Virtual Powerline to debug and test your SALad application.<br />
Although very convenient for code development, simulation is no substitute for realworld<br />
testing. Be sure to thoroughly shake out your application using real hardware<br />
before pronouncing it finished!<br />
In This Section<br />
PLC Simulator<br />
Explains how to use the PLC Simulator.<br />
Virtual Powerline<br />
Shows how to set up a software-simulated powerline<br />
environment.<br />
Virtual LampLinc<br />
Explains how to add software-simulated LampLinc devices to the Virtual<br />
Powerline.<br />
October 14, 2005 © 2005 Smarthome Technology
PLC Simulator<br />
Developer’s <strong>Guide</strong> Page 205<br />
The PLC Simulator is a pure-software version of a real PLC running on your PC. To<br />
use the PLC Simulator in place of a real PLC, turn it on by choosing<br />
the Mode-<br />
>Simulator menu item (see Menu – Mode).<br />
The PLC Simulator can do everything that a real PLC can do, but it is more<br />
transparent, thanks to a set of special software tools. These tools appear in the SIM<br />
Control window, which looks like this:<br />
For a complete explanation of how to use these tools, see the SIM Control section.<br />
October 14, 2005 © 2005 Smarthome Technology
Virtual Powerline<br />
Developer’s <strong>Guide</strong> Page 206<br />
The Virtual Powerline is a software-simulated powerline environment that works in<br />
conjunction with the PLC Simulator. To turn it on, choose the Virtual Devices-<br />
>Powerline menu item (see Menu – Virtual Devices). The Virtual Powerline will<br />
appear as a separate window that looks like this:<br />
The button at the top will be labeled Enable Powerline if the Virtual Powerline is<br />
currently disabled, or else it will say Disable Powerline while the Virtual Powerline is<br />
enabled. To use the Virtual Powerline, enable it. If the PLC Simulator is not running,<br />
turn it on, or if it is running, you may have to ‘Unplug’ it then ‘Plug’ it back in. When<br />
the PLC Simulator is using the Virtual Powerline properly, the message<br />
connection accepted<br />
will appear in the Virtual Powerline’s text box. The same message will appear every<br />
time you connect a virtual device, such as a Virtual LampLinc. When you remove a<br />
virtual device you will get the message<br />
connection removed<br />
You can place a message on the Virtual Powerline by typing the ASCII string you<br />
want to send in the box to the left of the Place on PL button, then pressing the<br />
button. The string you sent will appear in the text box.<br />
<strong>INSTEON</strong> messages that appear in the Virtual Powerline will show up as hex bytes<br />
preceded by A: in the text box.<br />
To stop using the Virtual Powerline, close its window.<br />
October 14, 2005 © 2005 Smarthome Technology
Virtual LampLinc<br />
Developer’s <strong>Guide</strong> Page 207<br />
Virtual LampLinc devices are software simulations of real Smarthome LampLinc V2<br />
Dimmers. Virtual LampLincs are connected to a Virtual Powerline,<br />
which in turn<br />
connects<br />
to a PLC Simulator. To launch a Virtual LampLinc, choose the Virtual<br />
Devices->LampLinc<br />
menu item (see Menu – Virtual Devices).<br />
The Virtual LampLinc<br />
will appear<br />
as a separate window that looks like this:<br />
The text box labeled <strong>INSTEON</strong> Address (A.B.C) at the<br />
top of the window contains the 3-byte ID of the Virtual<br />
LampLinc. This will be a unique number for each<br />
Virtual LampLinc that you launch. If you wish to<br />
assign a different ID, type it in the text box as three<br />
decimal digits separated by periods.<br />
The Zone: pulldown box lets you place Virtual<br />
LampLincs on the Virtual Powerline at varying<br />
simulated distances from one another. The greater<br />
the difference between Zone numbers, the greater the<br />
simulated distance between LampLincs. This lets you<br />
simulate powerline environments that require multiple<br />
hops for <strong>INSTEON</strong> messages to get through (see<br />
<strong>INSTEON</strong> Message Hopping,<br />
above).<br />
You can simulate plugging in or unplugging a Virtual<br />
LampLinc with the button that will be labeled (IN) Click<br />
to Unplug or else Plug In.<br />
The black circle at the bottom right of the picture of<br />
the LampLinc is the simulated SET Button, which you<br />
can push with the mouse. The white circle below that<br />
is the simulated white Status LED, which you can view.<br />
The square at the bottom shows the current dimming<br />
state of the Virtual LampLinc. Its color ranges<br />
from<br />
black for off, through various shades of gray, to white<br />
for full on.<br />
You can launch multiple<br />
Virtual LampLincs by rightclicking<br />
anywhere in a Virtual LampLinc window to<br />
display a popup menu that<br />
looks like this:<br />
Choose Spawn 4 more to create four more Virtual LampLincs, each in a separate<br />
window, and each with a different <strong>INSTEON</strong> Address. Choose Auto-Position All to<br />
neatly tile all open Virtual LampLinc windows. If you choose Auto-Position and Zone<br />
All, groups of Virtual LampLincs will appear in different Virtual Powerline zones.<br />
Choose Quit All to close all of the Virtual LampLinc devices at once.<br />
October 14, 2005 © 2005 Smarthome Technology
IDE Keyboard Shortcuts<br />
Developer’s <strong>Guide</strong> Page 208<br />
The table below shows how you can use the keyboard to perform common actions in<br />
the IDE.<br />
Key Action<br />
Ctrl-A Select all text in the currently displayed<br />
editor file<br />
Ctrl-X Cut selected text in the currently displayed editor file<br />
Ctrl-C Copy selected text in the currently displayed editor file<br />
Ctrl-V Paste selected<br />
text in the currently displayed editor file<br />
Ctrl-S Save the currently displayed editor file<br />
Alt-G Go to line number<br />
Ctrl-F Find a search string<br />
Ctrl-R Find a search string and replace it with another string<br />
Ctrl-Down Find next occurrence of search string<br />
Ctrl-Up Find previous occurrence of search string<br />
Ctrl-F4 Close currently displayed source file<br />
Ctrl-(left mouse click) If cursor is on an ‘Include’ file, open the file<br />
F2 (in debug mode) Stop the program<br />
F8 (in debug mode) Single Step the program<br />
F9 (not in debug mode) Compile and Download the program to the PLC<br />
F9 (in debug mode) Run the program<br />
October 14, 2005 © 2005 Smarthome Technology
Developer’s <strong>Guide</strong> Page 209<br />
Smarthome Device Manager Reference<br />
This section documents the Smarthome Device Manager (SDM). SDM is in the class<br />
of Manager Applications, which are programs that run on computing devices external<br />
to an <strong>INSTEON</strong> network and expose a high-level interface to the outside world.<br />
In This Section<br />
SDM Introduction<br />
Gives an overview of the SDM and lists system requirements.<br />
SDM Quick Test<br />
Gets you up and running using either a browser or SDM’s Main Window.<br />
SDM Commands<br />
Lists the available SDM Commands.<br />
SDM Windows Registry Settings<br />
Gives the Windows Registry settings that SDM uses.<br />
October 14, 2005 © 2005 Smarthome Technology
SDM Introduction<br />
Developer’s <strong>Guide</strong> Page 210<br />
The Smarthome Device Manager (SDM) is a communication and translation<br />
gateway t o The Smarthome PowerLinc Controller (PLC). Developers use simple text<br />
commands (Home Networking Language) through ActiveX or HTTP calls to<br />
communicate over<br />
<strong>INSTEON</strong> or X10 without the hassle of dealing with USB packets<br />
or RS232 resource issues.<br />
These commands will also be extended to PowerLinc/ IP and other Internet<br />
transports.<br />
Usi cation,<br />
whether in Macromedia Flash ® ng the Smarthome Device Manager, developers can focus on their appli<br />
® ® ® ®<br />
, Java , .NET or even in a Word document, Excel<br />
spreadsheet,<br />
or a PowerPoint ® presentation.<br />
Commands such as "SetOnLevelText=01.02.03,ON"<br />
perform the action and return a<br />
response, providing developers with simple and<br />
reliable control. Additional<br />
commands such as "speak," inet," and "mailto" further provide the developer with<br />
powerful capabilities.<br />
SDM<br />
System Requirements<br />
SDM Platforms<br />
Windows<br />
XP, 2000, NT (serial only), Me, 98, and 95 (serial only).<br />
SDM Programming Platforms<br />
any language that provides<br />
either ActiveX, HTTP, or shell calls including (Java,<br />
VB, .NET, C#, C++, Delphi, Flash, Perl, ASP, PHP, VB/W/JScript, Tcl, Python and<br />
more).<br />
SDM Resources<br />
HTTP Server uses port 9020 and offers a server-pull method to facilitate firewalls.<br />
Connects via COM1~COM255 or USB.<br />
PowerLinc Controller Firmware Requirement<br />
2.8 or better<br />
October 14, 2005 © 2005 Smarthome Technology
SDM Quick Test<br />
Developer’s <strong>Guide</strong> Page 211<br />
You can get the SDM up and running quickly using either a browser or SDM’s Main<br />
Window.<br />
In This Section<br />
SDM Test Using SDM’s Main Window<br />
Use SDM’s Main Window to interface with SDM.<br />
SDM Test Using a Browser<br />
Use a browser like Internet Explorer or FireFox to interface with SDM.<br />
SDM Test Using SDM’s Main Window<br />
Use SDM’s Main Window to interface with SDM.<br />
SDM Test Using a Browser<br />
1. Run Smarthome Device Manager (SDM2Server.exe). An icon will appear in<br />
your systray (normally at the lower right of your screen).<br />
2. Run a browser (such as Internet Explorer or FireFox).<br />
3. Type http://localhost:9020/abc.txt?isResponding into the browser as the<br />
URL.<br />
4. You should see a textual response isresponding=False or isResponding=True with<br />
other cached responses.<br />
October 14, 2005 © 2005 Smarthome Technology
Developer’s <strong>Guide</strong> Page 212<br />
SDM Test Using SDM’s Main Window<br />
1. Run Smarthome Device Manager (SDM2Server.exe). An icon will appear in<br />
your systray<br />
(normally at the lower right of your screen).<br />
2. Single-click on the icon and SD M’s<br />
Main Window will appear.<br />
3.<br />
Type isresponding into the bottom text box and press Send.<br />
4. You should see a textual<br />
response isresponding=False or isResponding=True with<br />
other cached response s.<br />
October 14, 2005 © 2005 Smarthome Technology
SDM Commands<br />
Developer’s <strong>Guide</strong> Page 213<br />
This section lists and explains the available SDM Commands.<br />
In This Section<br />
SDM Commands – Getting Started<br />
Utility commands for managing the PLC.<br />
SDM Commands – Home Control<br />
Commands for controlling <strong>INSTEON</strong> and X10 devices.<br />
SDM Commands – Notification Responses<br />
Notifications of <strong>INSTEON</strong>, X10, and serial communication reception.<br />
SDM Commands – Direct Communications<br />
Low-level <strong>INSTEON</strong>, X10, and serial communication commands.<br />
SDM Commands – Memory<br />
Commands for reading and writing PLC memory.<br />
SDM Commands – PLC Control<br />
Commands for managing the PLC, including the realtime clock.<br />
SDM Commands – Device Manager Control<br />
Commands for managing the SDM itself.<br />
SDM Commands – Link Datab ase Management<br />
Commands for searching and setting Link Databases in the PLC and remote<br />
<strong>INSTEON</strong> devices.<br />
SDM Commands – Timers<br />
Commands to create and delete timers, and to manage sunrise and sunset times.<br />
October 14, 2005 © 2005 Smarthome Technology
SDM Commands – Getting Started<br />
Developer’s <strong>Guide</strong> Page 214<br />
port= - sets the sticky, global PLC port (COM#,USB4,SIM28,?). Sending<br />
a question-mark '?' causes the port to be found. Use getport= to read the found<br />
port. The port is saved in the<br />
registry and reused upon restart of the Smarthome<br />
Device Manager.<br />
Examples: port=COM1 or port=USB4 or port=? or port=SIM28<br />
isResponding - asks the Device Manager if the port is responding (sends 0x02<br />
0x48) and responds true or false. This also reads the map for proper name-based<br />
downloading. This is the ultimate heartbeat method to determine if the PLC is<br />
connected and talking.<br />
Example: isResponding - returns isResponding=true<br />
addid= - add a device's ID to the PLC's database.<br />
Example: addid= 04.05.06<br />
(only if necessary, such as the LED blinking or the PLC not communicating)<br />
downloadCoreApp[=clear] - downloads the included core application to the PLC so<br />
that it can communicate to the Smarthome Device Manager. The optional =clear<br />
parameter also instructs the core application to clear the link table database after<br />
downloading.<br />
Example: downloadCoreApp<br />
setOnLevelText=, [,] - set on-level<br />
status (ON/OFF/dec%/dec/0xHex) of an ID, optionally specifying the number of<br />
hops. (defaults to 3 hops).<br />
Examples: setOnLevelText=04.05.06,ON or setOnLevelText=04.05.06,49% or<br />
setOnLevelText=04.05.06,127 or setOnLevelRaw=04.05.06,0x7F<br />
October 14, 2005 © 2005 Smarthome Technology
SDM Commands – Home Control<br />
Developer’s <strong>Guide</strong> Page 215<br />
setOnLevelText=,[,] - set on-level<br />
status (ON/OFF/dec%/dec/0xHex) of an ID, optionally specifying the number of<br />
hops. (defaults to 3 hops).<br />
Examples: setOnLevelText=04.05.06,ON<br />
or setOnLevelText=04.05.06,49% or<br />
setOnLevelText=04.05.06,127 or setOnLevelRaw=04.05.06,0x7F<br />
getOnLevelText=[,]<br />
- get on-level status from an ID as a<br />
text representation, optionally specifying the number of hops. (defaults to 3 hops).<br />
Returns ON,OFF,OUT,or percentage of on (1-99%).<br />
Examples: getOnLevelText=04.05.06. Returns getOnLevelText=04.05.06,ON or<br />
getOnLevelText=04.05.06,49%<br />
sendX10=[,] - sends x10 addresses<br />
and commands.<br />
Example: sendX10=A1,AON or sendX10=A1,A2 or sendX10=AON<br />
sendGroupBroadcast=,[,][,] - sends a<br />
broadcast from the PowerLinc Controller with the included group ID, and command1<br />
(ON/OFF/hex), and optional command2 (defaults to 0) and hops (defaults to 3).<br />
October 14, 2005 © 2005 Smarthome Technology
Developer’s <strong>Guide</strong> Page 216<br />
SDM Commands – Notification Responses<br />
These are for uninitiated messages.<br />
eventRaw= - notification of an event in hex.<br />
Example: eventRaw=0A<br />
receiveX10= - notification of an X10 address or command<br />
received, in text.<br />
Example: receiveX10=A1 or receiveX10=A On<br />
receiveX10raw= - notification of an X10<br />
address or command received, in hex form. x10type is zero (0) for an address, or<br />
one (1) for a command.<br />
Example: receiveX10raw=00<br />
66<br />
receive<strong>INSTEON</strong>raw= - notification of an <strong>INSTEON</strong><br />
message received. The number of bytes varies depending upon the eventID and<br />
whether the message is standard or extended.<br />
Example: receive<strong>INSTEON</strong>raw=02 04 05 06 00 00 11 8F 01 00<br />
enrolled=,, - notification that an<br />
<strong>INSTEON</strong> device was enrolled into the PLC.<br />
NOTE: linked= will replace enrolled= ... linked=, ,<br />
, [, , ]<br />
usbarrival=,,,, -<br />
notification that the PLC was connected. (Specific to PLC from Smarthome).<br />
Example: usbarrival=4287,4,1024,SmartHome,SmartHome PowerLinc USB E,<br />
usbunplugged=4287,4,1024,,, - notification that the PLC was disconnected (once<br />
connected). (Specific to PLC from Smarthome).<br />
Example: usbunplugged=4287,4,1024,,,<br />
progress=<br />
October 14, 2005 © 2005 Smarthome Technology
Developer’s <strong>Guide</strong> Page 217<br />
SDM Commands – Direct Communications<br />
These are for raw, low-level communication.<br />
send<strong>INSTEON</strong>raw= - send the 9 (standard) or 23 (extended)<br />
<strong>INSTEON</strong>bytes from the PLC.<br />
Example: send<strong>INSTEON</strong>raw=01 02 03 04 05 06 0F 11 FF (send from unit 01.02.03<br />
(which is overwritten with the actual PLC ID) to unit 04.05.06, with 3 hops, an ON at<br />
full brightness).<br />
sendrec<strong>INSTEON</strong>raw/SRIR= - send the 9 (standard) or 23<br />
(extended) <strong>INSTEON</strong>bytes from the PLC *and wait for the response (ACK/NAK)*.<br />
Examples: sendrec<strong>INSTEON</strong>raw=01 02 03 04 05 06 0F 11 FF or SRIR=01 02 03 07<br />
08 09 0F 13 00. Returns SRIR=04,07 08 09 01 02 03 2F 13 00 (the returned ACK<br />
packet response).<br />
getOnLevelRaw=[,] - get on-level status from an ID as a<br />
hexbyte representation, optionally specifying the number of hops. (defaults to 3<br />
hops). Returns 00-FF.<br />
Examples: getOnLevelRaw=04.05.06. Returns getOnLevelRaw=04.05.06,7F<br />
setOnLevelRaw=,[,< hops>] - set on-level<br />
status from an ID as a hexbyte<br />
representation, optionally specifying the number of<br />
hops. (defaults to 3 hops). Set/Returns 00-FF.<br />
Examples: setOnLevelRaw=04.05.06,7F. Returns setOnLevelRaw=04.05.06,7F<br />
sendX10raw=, - send an X10 address or<br />
command byte. x10type is zero (0) for an address, or one (1) for a command.<br />
Example: sendX10raw=00, 66 (sends A1 address).<br />
sendPLC= - send direct raw hex bytes to the PLC, as if through a direct<br />
connection (such as serial).<br />
Example: sendPLC=02 40 01 65 00 01 FF 33 66<br />
sendEventRaw= - sends an event (00-FF) for the PLC to execute (see<br />
<strong>INSTEON</strong> EVENTS).<br />
October 14, 2005 © 2005 Smarthome Technology
SDM Commands – Memory<br />
Developer’s <strong>Guide</strong> Page 218<br />
setImage=, - downloads data to the address (mapfriendly).<br />
Examples: setImage=0x0040,02 FF or setImage=NTL_TIMERS,02 FF<br />
getImage=, - uploads the image to the PC,<br />
returns hex bytes.<br />
(map-friendly).<br />
Examples: getImage=0x0040,2 returns getImage=0x0040,00<br />
00<br />
setBit=,[,] - sets the bit (0-7) at the address (mapfriendly)<br />
with an optional value of 1(set) or 0(clear) (defaults to 1).<br />
Example setBit=0x0040,4 or setBit=0x0040,4,0<br />
clearBit=, - clears the bit (0-7) at the address (map-friendly).<br />
Example clearBit=0x0040,4<br />
downloadCoreApp[=clear] - downloads the included core application to the<br />
PLC so<br />
that it can communicate to the Smarthome Device<br />
Manager. The optional =clear<br />
parameter also instructs the core application to clear the link table database after<br />
downloading. Automatically resets the PLC after download.<br />
Example: downloadCoreApp<br />
downloadSALadFile= - downloads the SALad program<br />
filename<br />
provided (as a binary/compiled file, not hex). Automatically resets the PLC after<br />
download.<br />
Example: downloadSALadFile=coreUser.slb<br />
downloadBinaryFile=, - downloads the binary file to the<br />
address provided. This command<br />
does *not* automatically reset the PLC after<br />
download.<br />
Example: downloadBinaryFile=,myTable.bin<br />
verifyCoreApp - returns true or false with information whether the currently<br />
download application matches<br />
the expected core application.<br />
Example: verifyCoreApp<br />
October 14, 2005 © 2005 Smarthome Technology
SDM Commands – PLC Control<br />
Developer’s <strong>Guide</strong> Page 219<br />
port= - sets the sticky,<br />
global PLC port (COM#,USB4,SIM28,?). Sending<br />
a question-mark<br />
'?' causes the port to be found. Use getport= to read the found<br />
port. The port is saved in the registry<br />
and reused upon restart of the Smarthome<br />
Device Manager.<br />
Examples: port=COM1 or port=USB4 or port=? or port=SIM28<br />
getport - returns the current sticky, global PLC port.<br />
Example: getport returns getport=USB4<br />
getFirmware - returns the PLC firmware revision.<br />
Example: getFirmware returns getFirmware=2.9<br />
sendHardReset - resets the SALad application, reinitializes (executes the INIT<br />
event).<br />
getClock - gets the current PLC clock (which is reset from the RTClock on<br />
initialization/plugin in the Core Application).<br />
Example: getClock returns getclock=true,8/12/2005 5:03:39 PM<br />
getRTClock - gets the current real-time clock.<br />
Example: getRTClock returns getclock=true,8/12/2005 5:03:39 PM<br />
setClock - sets BOTH the real-time clock and the running clock.<br />
Example: setClock=8/12/2004 5:03:39 PM<br />
setRunningClock - sets only the running clock, not the real-time clock. This means<br />
that when the PLC is plugged in next or reset, the core app will copy the real-time<br />
clock over the running clock.<br />
Example: setRunningClock=8/12/2004 5:03:39 PM<br />
setRTClock - sets only the real-time clock, not the running clock. This means that<br />
when the PLC is plugged in next or reset, the core app will copy the real-time clock<br />
over the running clock.<br />
Example: setRTClock=8/12/2004 5:03:39 PM<br />
connect - connect to the PLC after a disconnection (connecting is done automatically<br />
at startup).<br />
Example: connect<br />
disconnect - disconnect the PLC's port connection.<br />
Example: disconnect<br />
isResponding - asks the Device Manager if the port is responding (sends 0x02<br />
0x48) and responds true or false. This also reads the map for proper name-based<br />
downloading. This is the ultimate heartbeat method to determine if the PLC is<br />
connected and talking.<br />
Example: isResponding - returns isResponding=true<br />
getplcstatus - returns set of statuses for PowerLinc Controller (port, connection,<br />
etc).<br />
October 14, 2005 © 2005 Smarthome Technology
Example: getplcstatus<br />
help - provides a quick visual list of commands.<br />
Example: help<br />
getMyID - returns the PLC's ID.<br />
Example: getMyID returns getMyID=01.02.03<br />
Developer’s <strong>Guide</strong> Page 220<br />
October 14, 2005 © 2005 Smarthome Technology
Developer’s <strong>Guide</strong> Page 221<br />
SDM<br />
Commands – Device Manager Control<br />
setTextMode= - sets the global communication format that the Device<br />
Manager uses to receive and respond.<br />
Currently 'text' (default) and 'flash' are<br />
supported. 'flash' mode adds ampersands (&) around each response in order for the<br />
loadVariables()<br />
function to receive values from Macromedia Flash or SwishMax type<br />
clients.<br />
nop - does nothing, but allows an HTTP connection to return collected data to the<br />
client.<br />
echo - echoes the text simply to see if the ActiveX or HTTP communication is<br />
working.<br />
_localbytes= - turns on/off local (window) Device Manager byte-level<br />
debugging.<br />
remotebytes= - turns on/off local (window) Device Manager byte-level<br />
debugging.<br />
setBlocked= - (default false) turns on/off global blocking of<br />
commands. When blocked, the action is executed before receiving a response and<br />
returning to the client. When not blocked, the client is returned a true response that<br />
the command was accepted for execution by the Device Manager. When the actual<br />
response is received by the Device Manager, it is sent to the client via ActiveX, or<br />
queued for return via HTTP. (use NOP to get results when no execution action is<br />
necessary).<br />
setPageSizeThrottle= - (default true) allows global throttling of the<br />
downloads in case of errors. The download page size shrinks when multiple<br />
consecutive errors are received. The page size grows when multiple consecutive<br />
successes are received.<br />
setPageErrors= - (default 7) sets the global maximum number of<br />
consecutive retries before a download actually fails.<br />
setPageSize= - (default 32) sets the global packet size for<br />
downloading. When throttling is true, this value automatically shrinks and grows.<br />
if=,,[,] - executes the<br />
command, matches against the matchResult. If true, returns the trueText. If false<br />
(and the falseText is present), returns the falseText.<br />
Example: if=getFirmware,2.9,good,bad<br />
ifexec=,,[,] -<br />
executes the command, matches against the matchResult. If true, executes the<br />
trueCommand. If false (and the falseCommand is present), executes the<br />
falseCommand.<br />
Example: ifexec=getFirmware,2.9,"setOnLevelText=00.02.BA,ON",nop<br />
setAuthUsername= - allows user to set an authorization username for<br />
the http/web connection to require. Shipped default is empty - no authorization<br />
required.<br />
Example: setAuthUsername=me<br />
October 14, 2005 © 2005 Smarthome Technology
Developer’s <strong>Guide</strong> Page 222<br />
setAuthPassword= - allows user to set an authorization password for<br />
the http/web connection to require. Shipped default is empty - no authorization<br />
required. To clear, send setAuthPassword with no password.<br />
Example: setAuthPassword= 12345<br />
October 14, 2005 © 2005 Smarthome Technology
Developer’s <strong>Guide</strong> Page 223<br />
SDM<br />
Commands – Link Database Management<br />
addID= - add a device's ID to the PLC's database.<br />
Example: addID=04.05.06<br />
removeID= - deletes a device's ID from the PLC's database.<br />
Example: removeID=04.05.06<br />
getRemoteRecord=, [,] - gets and block-returns remote database records.<br />
Examples: getRemoteRecord=04.05.06,2 or getRemoteRecord=04.05.06,2,3.<br />
Returns getremoterecord=<br />
=====RECORDS BEGIN=====<br />
remoterec(04.05.06):#2:A2 01 00 D0 80 FE 1F 00<br />
remoterec(04.05.06):#3:A2 02 00 6B C2 FE 1F 00<br />
=====RECORDS END=====<br />
getLinks - returns a block-list of records in the PowerLinc Controller.<br />
Example: getLinks<br />
getRemoteGroupRecord=[:] , <br />
[,] [,] - scans the remote<strong>INSTEON</strong>id's (non-PLC)<br />
database for the sourceID (defaults to PLC's ID) and groupID, or uses the recno<br />
provided. Returns full record information as<br />
getRemoteGroupRecord=, , ,<br />
, <br />
Example: getRemoteGroupRecord=04.05.06, 1 returns<br />
getRemoteGroupRecord=04.05.06, 01.02.03,1,50%,31<br />
setRemoteGroupRecord=[:] ,<br />
,,, , -<br />
scans the remote<strong>INSTEON</strong>id's (non-PLC) database for the sourceID (defaults to PLC's<br />
ID), and groupID, or uses the recno provided. Sets full record information.<br />
Example: setRemoteGroupRecord=1:04.05.06, 1, 01.02.03,3,50%,31 or<br />
setRemoteGroupRecord=04.05.06, 1, 01.02.03,3,50%,31<br />
setPresetDim=, , <br />
[,] [,] - sets the preset dim value for the PLC or<br />
source<strong>INSTEON</strong>id (defaults to PLC's id) in the remote<strong>INSTEON</strong>id's database.<br />
Example: setPresetDim=04.05.06, 1, 25%<br />
setRampRate=, , <br />
[,] [,] - sets the ramprate dim value for the PLC or<br />
source<strong>INSTEON</strong>id (defaults to PLC's id) in the remote<strong>INSTEON</strong>id's database.<br />
(RAMPRATE VALUES ARE 0x00-slow to 0x1F-fast).<br />
Example: setPresetDim=04.05.06, 1, 0x1F<br />
getPresetDim=, , [,]<br />
[,] - gets the preset dim value for the PLC or source<strong>INSTEON</strong>id (defaults to<br />
PLC's id) in the remote<strong>INSTEON</strong>id's database.<br />
Example: getPresetDim=04.05.06, 1<br />
October 14, 2005 © 2005 Smarthome Technology
Developer’s <strong>Guide</strong> Page 224<br />
getRampRate=, ,<br />
[,]<br />
[,] - gets the ramprate dim value for the PLC or source<strong>INSTEON</strong>id (defaults<br />
to PLC's id) in the remote<strong>INSTEON</strong>id's database. (RAMPRATE VALUES ARE 0x00-slow<br />
to 0x1F-fast).<br />
Example: setPresetDim=04.05.06, 1<br />
October 14, 2005 © 2005 Smarthome Technology
SDM Commands – Timers<br />
Developer’s <strong>Guide</strong> Page 225<br />
USAGE NOTES: Before adding/using timers, you must once download<br />
the<br />
timerCoreApp.slb file and use the (clearTimers) command. This resets all internal<br />
tables before you can add timers. Also, for using sunset/sunrise, you need to set<br />
your state/city (setStateCity)<br />
or lat/long (setLatLong) and download the sunset<br />
table (downloadSunTable).<br />
downloadSALadFile=timerCoreApp.slb - downloads the timer core application,<br />
required for timer usage. Downloading WILL prevent you from listing timers until<br />
clearTimers is used.<br />
clearTimers - clears<br />
the timer tables. Eliminates all timers and resets timer<br />
variables.<br />
listTimers - block-lists the currently existing timers. Returns ,<br />
, , , , . See addTimer for DOW/Sec info.<br />
Example: listTimers returns listtimers=beginlist<br />
timer=1,active,19:53,04.05.06:OFF,SuSaFThWTuM,NOSEC<br />
timer=2,active,20:00,04.05.06:50%,SuSaFThWTuM,NOSEC<br />
timer=3,active,19:59,<strong>INSTEON</strong>:04<br />
05 06 4F 11 00,M,SEC<br />
timer=4,active,sunset+20,04.05.06:OFF,SuSaFThWTuM,NOSEC<br />
endlist<br />
getTimer= - same as listTimers, except lists a single timer (not<br />
block-listed) specified by .<br />
Example: getTimer=2 - returns<br />
timer=2,active,20:00,04.05.06:50%,SuSaFThWTuM,NOSEC.<br />
addTimer=,<br />
[,]<br />
[,] [,] - at the time specified, send<br />
on/off/0xhex/dec/brightness% to the <strong>INSTEON</strong>-ID. < time> can either be military, or<br />
sunrise or sunset. If 'sunrise' or 'sunset' is specified, you can specify the number<br />
of<br />
offset minutes.<br />
uses M, Tu, W, Th, F, Sa, Su as specifiers (without spaces or<br />
commas). 'All' is an abbrieviation for MTuWThFSaSu. The<br />
defaults are <br />
.<br />
Examples: addTimer=14:30,04.05.06:25% or addTimer=sunset+10,04.05.06:OFF<br />
or addTimer=sunrise-25,04.05.06:ON,MTuWF,SEC<br />
addTimer=, [,]<br />
[,] [,] - at the time specified, send 6 bytes via<br />
<strong>INSTEON</strong>.<br />
can either be military, or sunrise or sunset. If 'sunrise'<br />
or 'sunset' is<br />
specified, you can specify the number of offset minutes. uses M, Tu, W, Th,<br />
F, Sa, Su as specifiers (without spaces or commas). 'All' is an abbrieviation for<br />
MTuWThFSaSu. The defaults are <br />
.<br />
Examples: addTimer=14:30,<strong>INSTEON</strong>:04 05 06 0F 11 80 or<br />
addTimer=sunset+10,<strong>INSTEON</strong>:04 05 06 0F 13 00 or addTimer=sunrise-<br />
25,<strong>INSTEON</strong>:04 05 06 0F 11 FE,MTuWF,SEC<br />
setTimer=, , [,] [,] [,] - same as addTimer, except<br />
October 14, 2005 © 2005 Smarthome Technology
Developer’s <strong>Guide</strong> Page 226<br />
setTimer overwrites a specific timer record specified by recordnumber, which is listed<br />
in the listTimers.<br />
Example: setTimer=1,14:30,04.05.06:25% overwrites record 1.<br />
deleteTimer= - deletes the timer specified by as<br />
listed<br />
by listTimers.<br />
Example: deleteTimer=1<br />
setStateCity=sets the latitude and longitude and sunrise/sunset information based<br />
on a state and city name. Information located in places.csv and places.idx for UI to<br />
enumerate. You can query getLatLong or getSunrise or getSunset after setting the<br />
State and City.<br />
Example: setStateCity=CA,IRVINE or setStateCity=California,tustin<br />
setLatLong=sets the latitude and longitude and sunrise/sunset information. You can<br />
query getLatLong or getSunrise or getSunset after setting this.<br />
Example: setLatLong=33.684065,-117.792581<br />
getLatLong - returns the currently set latitude and longitude used for sunrise and<br />
sunset calculations.<br />
Example:<br />
getlatlong - returns 33.684065,-117.792581<br />
downloadSunTable - verifies that the TimerCoreApp is installed and downloads the<br />
sunrise/sunset table (based on latitude and longitude) to the PLC for use within the<br />
TimerCoreApp. This is required once to enable the sunrise/sunset time specifications.<br />
Example: downloadSunTable<br />
getsunrise - returns today's sunrise time as calculated with the setStateCity or<br />
setLatLong.<br />
Example: getsunrise returns 8/30/2005 6:24:00 AM<br />
getsunset - returns today's sunset time as calculated with the setStateCity or<br />
setLatLong.<br />
Example: getsunrise returns 8/30/2005 7:20:00 PM<br />
getnextalarmtime - returns the PLC's next scheduled alarm time. Note that this<br />
may not exactly match the time specified for timers where SECurity is set. When the<br />
minutes from midnight (getminutes) matches the getnextalarmtime, the alarm(s)<br />
that matches (or not for security) will fire.<br />
Example: getnextalarmtime returns HH:MM such as 14:25<br />
setnextalarmtime=HH:MM - set the PLC's next alarm time. Useful to skip alarms, if<br />
necessary, while they are reset for the next day. When the minutes from midnight<br />
(getminutes) matches the getnextalarmtime, the alarm(s) that matches (or not for<br />
security) will fire.<br />
Example: setnextalarmtime=18:00 - essentially skips (today) timers until 6pm.<br />
getminutes - returns the PLC's current minutes from midnight, set on initialization<br />
and auto-incremented each minute.<br />
Example: getminutes returns HH:MM such as 15:25.<br />
October 14, 2005 © 2005 Smarthome Technology
Developer’s <strong>Guide</strong> Page 227<br />
setminutes=HH:MM - set the PLC's current minutes from midnight,<br />
normally set on<br />
initialization and auto-incremented each minute. Useful to debug<br />
timers by setting<br />
the PLC's match of alarms without actually<br />
changing the PLC's clock.<br />
Example: setminutes=18:00<br />
October 14, 2005 © 2005 Smarthome Technology
Developer’s <strong>Guide</strong> Page 228<br />
SDM Windows Registry Settings<br />
The Device Manager's root location<br />
is:<br />
HKEY_CURRENT_USER\Software\Smarthome\<br />
SmarthomeDeviceManager<br />
Valuename: port<br />
= - sticky global port for Device Manager to connect -<br />
USB4 or COM1..COM255. Set from the port= command.<br />
Valuename:<br />
servername = - Device Manager's executable for<br />
clients<br />
to autorun.<br />
Valuename: usehttp = <br />
- allow the http server to accept connections.<br />
(Defaults<br />
to true)<br />
Valuename: httpport = - when the http server activates, the server<br />
uses this port (Defaults to 9020).<br />
October 14, 2005 © 2005 Smarthome Technology
Developer’s <strong>Guide</strong> Page 229<br />
<strong>INSTEON</strong> Hardware Development<br />
Documentation<br />
In This Section<br />
Hardware Overview<br />
Gives an overview of <strong>INSTEON</strong> hardware including block diagrams and physical<br />
diagrams of the HDK unit.<br />
Hardware Reference Designs<br />
Shows schematics for the Main Board (Isolated and Non-Isolated) and Daughter<br />
Board.<br />
Hardware Overview<br />
The HDK consists of a Main Board and a Daughter Board.<br />
Main Board<br />
The Main Board comes in 2 varieties: Isolated (for interfacing <strong>INSTEON</strong> networks<br />
sensitive equipment), and Non-Isolated (for equipment that has direct access to<br />
120 VAC). The Main Board and Daughter Board schematics are shown in later<br />
sections of this document. The Main Board consists of:<br />
• <strong>INSTEON</strong> Powerline Interface<br />
• <strong>INSTEON</strong> Micro Controller Unit (MCU)<br />
• <strong>INSTEON</strong> Enrollment User Interface (Button / LED)<br />
• Power Supply<br />
Daughter Board<br />
The Daughter Board has an experimental area for you to develop your circuitry and<br />
makes available the signals from the Main Board. The Daughter Board consists of:<br />
• Experimental Design Area<br />
• Button for connecting Daughter Board Interrupt line to ground<br />
• LED connected to 1 General Purpose I/O line<br />
When connected to the Non-Isolated Main Board, the Daughter Board can make<br />
use of the following hardware:<br />
• LED to simulate Load Control<br />
• 11 Extra General Purpose I/O lines<br />
• 120 VAC<br />
October 14, 2005 © 2005 Smarthome Technology
Functional Block Diagram<br />
Developer’s <strong>Guide</strong> Page 230<br />
This diagram shows the functional blocks on each board. The Main board serves as<br />
the <strong>INSTEON</strong> modem. The <strong>INSTEON</strong> chip executes SALad application code. The<br />
Daughter Board functions as a place<br />
to develop OEM circuits.<br />
<strong>INSTEON</strong> HDK Hardware Block Diagram<br />
Optional EEPROM<br />
I2C<br />
22.1184 MHz Xtal<br />
Power Supply<br />
<strong>INSTEON</strong> Main Board<br />
<strong>INSTEON</strong> MCU<br />
Power Line Interface<br />
User Interface<br />
LED Button<br />
Power Line Tx Power Line Rx Load Control<br />
120VAC (Non-Isolated Only)<br />
I2C Bus<br />
TTL RS232<br />
HDK Daughter Board<br />
JP 1<br />
Level Converter<br />
RS232 Tranceiver<br />
11 General Purpose I/O Lines (Non-Isolated Only)<br />
1 General Purpose I/O Line<br />
Daughter Board Interrupt<br />
RTC<br />
32.768 KHz Xtal<br />
EEPROM<br />
RS232 4800,8,N,1<br />
OEM Experimental Circuit Design Area<br />
October 14, 2005 © 2005 Smarthome Technology
HDK Physical Diagrams<br />
HDK Physical Dimensions<br />
Developer’s <strong>Guide</strong> Page 231<br />
This diagram shows the physical dimensions of the HDK unit.<br />
October 14, 2005 © 2005 Smarthome Technology
HDK Daughter Card<br />
Developer’s <strong>Guide</strong> Page 232<br />
This diagram shows the HDK Daughter Board, and where signals and parts are<br />
located on the board.<br />
October 14, 2005 © 2005 Smarthome Technology
Hardware Reference Designs<br />
In This Section<br />
HDK Isolated Main Board<br />
Schematic.<br />
HDK Non-Isolated Main Board<br />
Schematic.<br />
HDK Daughter Board<br />
Schematic.<br />
Developer’s <strong>Guide</strong> Page 233<br />
October 14, 2005 © 2005 Smarthome Technology
HDK Isolated Main Board<br />
Developer’s <strong>Guide</strong> Page 234<br />
October 14, 2005 © 2005 Smarthome Technology
HDK Non-Isolated Main Board<br />
Developer’s <strong>Guide</strong> Page 235<br />
October 14, 2005 © 2005 Smarthome Technology
HDK Daughter Board<br />
Developer’s <strong>Guide</strong> Page 236<br />
October 14, 2005 © 2005 Smarthome Technology
CONCLUSION<br />
Developer’s <strong>Guide</strong> Page 237<br />
“Everything should be made as simple as possible, but not simpler.”<br />
Albert Einstein (1879-1955)<br />
Electronic Home Improvement is poised to become a major industry of the twenty<br />
first<br />
century. Three-quarters of homes in the U.S. now have computers and over<br />
two-thirds of those are connected to the Internet. WiFi wireless networking is in<br />
17% of homes. High-def TV is gaining momentum. But light switches, door locks,<br />
thermostats,<br />
smoke detectors, and security sensors cannot talk to one another.<br />
Without an infrastructure networking technology, there can be no hope for greater<br />
comfort, safety, convenience, and value brought about through<br />
interactivity. Homes<br />
will remain unaware that people live in them.<br />
For a technology to be adopted as infrastructure, it must be simple, affordable, and<br />
reliable.<br />
Not all technology that gets developed gets used. Sadly, a common pitfall<br />
for new technology is overdesign—engineers jus t can’t resist putting in all the latest<br />
wizardry. But with added performance, cost goes up and ease-of-use goes down.<br />
Simplicity<br />
is the principal asset of <strong>INSTEON</strong>. Installation is simple—<strong>INSTEON</strong> uses<br />
existing house wiring or the airwaves to carry messages. <strong>INSTEON</strong> needs no<br />
network controller—all devices are peers. Messages are not routed—they are<br />
simulcast. Device addresses are assigned at the factory—users don’t have to deal<br />
with network enrollment. Device linking is easy—just press a button on each device<br />
and they’re linked.<br />
Simplicity ensures reliability and low-cost. <strong>INSTEON</strong> is not intended to transport lots<br />
of data at high speed—reliable command and control is what it excels at. <strong>INSTEON</strong><br />
firmware, because it is simple, can run on the smallest microcontrollers using very<br />
little memory—and that means the lowest-possible cost.<br />
Developing applications for <strong>INSTEON</strong>-networked devices is also simple. Designers do<br />
not have to worry about the details of sending and receiving <strong>INSTEON</strong> messages, as<br />
laid out above, because those functions are handled in firmware. Application<br />
developers can use a simple scripting interface (Home Network Language) and<br />
Smarthome’s Device Manager to further simplify the interface to a network of<br />
<strong>INSTEON</strong> devices. Designers who wish to create new kinds of <strong>INSTEON</strong> devices can<br />
write the software for them using Smarthome’s Integrated Development<br />
Environment and the SALad embedded language.<br />
Although <strong>INSTEON</strong> is simple, that simplicity is never a limiting factor, because<br />
<strong>INSTEON</strong> Bridge devices can connect to outside resources such as computers, the<br />
Internet, and other networks whenever needed. SALad-enabled <strong>INSTEON</strong> devices<br />
can be upgraded at any time by downloading new SALad programs. Networks of<br />
<strong>INSTEON</strong> devices can evolve as the marketplace does.<br />
Smarthome’s mission is to make life more convenient, safe and fun. <strong>INSTEON</strong><br />
provides the infrastructure that can make that dream come true. Anyone can now<br />
create products that interact with each other, and with us, in remarkable new ways.<br />
What an interesting world it will be!<br />
October 14, 2005 © 2005 Smarthome Technology
NOTES<br />
Developer’s <strong>Guide</strong> Page 238<br />
1. Battery operated <strong>INSTEON</strong> RF devices, such as security sensors and handheld<br />
remote controls, must conserve power. Accordingly, they may optionally be<br />
configured so that they do not retransmit <strong>INSTEON</strong> messages from other<br />
<strong>INSTEON</strong> devices, but act as message originators only. Such devices can<br />
nevertheless both transmit and receive <strong>INSTEON</strong> messages, in order to allow<br />
simple setup procedures and to ensure network reliability.<br />
2. At a minimum, X10 compatibility means that <strong>INSTEON</strong> and X10 signals can<br />
coexist with each other on the powerline without mutual interference. <strong>INSTEON</strong>only<br />
powerline devices do not retransmit or amplify X10 signals. But X10<br />
compatibility also means that designers are free to create hybrid <strong>INSTEON</strong>/X10<br />
devices that operate equally well in both environments. By purchasing such<br />
hybrid devices, current users of legacy X10 products can easily upgrade to<br />
<strong>INSTEON</strong> without making their X10 investment obsolete.<br />
3. Firmware in the <strong>INSTEON</strong> Engine handles the CRC byte automatically, appending<br />
it to messages that it sends, and comparing it within messages that it receives.<br />
Applications post messages to and receive messages from the <strong>INSTEON</strong> Engine<br />
without the CRC byte being appended. See Message Integrity Byte for more<br />
information.<br />
October 14, 2005 © 2005 Smarthome Technology