xAP newbie

[Tcassio]

Can someone direct me to a good Geting started tutorial for xAP.

[garygfx]

Are you still looking for a good "getting started" guide to xAP? Me too. I'm sure the take up would increase if someone wrote a really simple guide for beginners. Most the ones I've seen assume you already know the xAP basics and jumps a few important chapters, so to speak.

The most enlightening intro is perhaps by CouchPotatoe: http://board.homeseer.com/showthread.php?t=89501

I still don't understand how HS is supposed to interact with xAP and how non-programmers (or those with a bit of vbs scripting skill) are meant to utilise data sent/received via xAP?

[Michael McSharry]

For a simple analogy we can use the X10 powerline. There are X10 modules for switches, chimes, lamps, sprinkler valves as well several other special purpose devices. These devices conform to an address space of A1 to P16 and to commands such as ON/OFF/DIM. An interface exists in Homeseer such as CM11A or Powerlinc to allow Homeseer to talk with these X10 devices.

There is an ethernet connection of the PC and a Homeseer interface to this ethernet connection with George's IP plugin and James's xAP plugin as well as some others. The xAP plugin implements a protocol with an address space and a command set. This just like the X10 analogy, but the address space can be larger and the command set is more extensive.

There are modules, called connectors, that can be run on any computer on the LAN. There can also be hardware that has an IP connection that can be used. A connector implements certain functionality just like the X10 module implements certain funtionality. For example, a connector may control an IR interface, a TIVO, a speaker switch, a CID device, etc.

The Homeseer interface model is primarily virtual devices. To turn on the X10 light at "A1" one sets the A1 virtual device Status to ON. There may be a plugin to Homeseer that controls a speaker switch to one of 8 settings. This plugin will have virtual device that represents the speaker switch and it will allow selection from one of 8 values.

An xAP connector can also control a speaker switch. The connector will accept xAP commands to set the position. The xAP plugin will associate a virtual device with the speaker switch just as was done with the Speaker Switch plugin. When a homeseer users sets a value on this virtual device the command with be received by the remote xAP connector and the action performed just like the action that would have been performed with the Homeseer Speaker Switch plugin.

If you have a widget you want to inteface with Homeseer you can write a Homeseer Widget plugin. Whenever you want to use the widget you will do it via Homeseer. Rather than a Widget plugin you could write a xAP Widget Connector. The connector can run anywhere on the LAN and everything on the LAN has the abiltiy to interact with it. This includes Homeseer with the virtual device paradymn.

If you are not up to writing plugins or connectors, but you would like to control existing interfaces then you can do it via script. Homeseer runs scripts that allow you communicate with the interface using the virtual device model. The same can be done with xapmcsScript which extends the basic scripting to include methods to send and receive xAP messages.

If you are not up to writing scripts then the Homeseer GUI provides basic virtual device functionality that works fine for manual control of interfaces that are via Homeseer plugins or xAP connectors.

George's IP plugin was mentioned earlier. It provides a low level IP scripting interface that makes no assumptions about the data that is carried over the interface. It is like a character stream like one sees from a serial COM port.
Think of it as delivering words that can be used by a script. The xAP plugin also accepts words over the IP interface, but it forms sentences and paragraphs so the words have a HA-oriented meaning. Homeseer also provides a Web interface. This is just another IP interface that uses HTTP as the language. The HTTP connector with which most are familiar is the typical Browser.

[garygfx]

Thanks Michael. Here's my humble account of what happened when I tried to get started with xAP earlier on today. Please set flames>Nil


I had no idea what I needed to download despite reading as many articles as I could find. I figured I should install the HS xAP plugin and xAP Desktop to start with.

The News Scroller didn't work (it just showed scrolling dashes), the Weather showed a question mark, and the Floorplan2 template didn't do much. None of these had any instructions that could explain why they aren't working or how to configure them properly. The only one I got working was the Homeseer Log which worked well and is a good demo of what xAP can do.

Next I installed xAP News which didn't work. It said something about checking a hub. This threw me for a while until I found an article about xAP hubs - I thought it meant my network hub! I read that only 1 xAP app can run at a time on the same PC so I downloaded a hub from another website. I think this was the 3rd xAP website I visited. The info and files a new user needs should really be on 1 site, not several IMHO. Or at least have 1 central xAP site that explains everything a new user needs to know. It's a bit like an Easter Egg hunt jumping between sites looking for nibbles to fill the gaps in my understanding.

After installing the hub everything stopped working. I eventually realised it was my software firewall (Sygate Personal Firewall) - I changed the settings to "allow all traffic". All of my ports are now open since I can't find out what ports xAP or the hub uses to communicate. Yes, I tried searching for help but the xAP sites come up with nothing.

I found out how to configure the HS plugin to use xAP events and send a message that popped up on a 2nd PC whenever someone walked past a motion sensor. Now I'm starting to see some practical uses for xAP!

Next I installed the xAP Speech Server. It has no instructions and I couldn't find any on the web. It runs but I have no idea what to do with it or if it can speak something on computer #2 if HS on computer #1 wants to say something?

The Floorplan app looked good so I installed that. It throws an error and crashes whenever I try to update one of the HS devices in the settings menu. I tried different types of devices (X10 and virtual) and it always crashes - runtime error 9 subscript out of range. Yes, I know it's a beta and I shouldn't complain about bugs in a beta.

I'm not knocking xAP, I think the concept is genius . I can see its potential now but I can also see what's stopping others from using it. Once past the initial shroud of mystery it's a case of trying to find out what you need to download to get started, seeing which apps work, which don't, and finding illusive instructions on how to use the apps and work out why they aren't working.

If any reader of this post hasn't tried xAP before then you need to know this:

• xAP lets you share devices between computers on your network (or Internet). It lets you send commands as well as receiving status info - this applies to all sorts of devices, not just HS devices.
• The HS xAP plugin is the first thing you need to download if you own HS
• If you want to run more than 1 xAP app on a PC you must install a hub. There are 3 versions and you can only run one: a Windows Service hub, a GUI hub, or just in a DOS box. [download]
• You have to install the .NET framework before running the hub (25mb)
• There is no installer for the hub, I think you're just meant to copy the files to a new directory and drag the exe into your startup folder.
• If you're running a decent software firewall (e.g. Sygate - not sure about ZoneAlarm?) you need to disable it unless you can figure out the ports to open up
• Don't expect much documentation if things aren't obvious or don't work

If anyone thinks I've been unfair on xAP then I will delete this msg as it's not my intention to upset anyone, only to help things progress. I had second thoughts on posting this but I'm sure I can't be the only one with these thoughts.

It's obvious that a massive amount of dedication has been put into xAP. It's very cool but needs to be made more accessible by producing clear instructions for newbies on how to get started, what each app does and how to troubleshoot. Unless xAP is not really intended for the average HA user?

[Michael McSharry]

I cannot help you much with all your lack of successes. I do use the viewer as a staple and I did try the desktop and got to the point where I understood what it did. In the early days I also used the xapFramework.net hub, but there were problems that Stuart and I just could not get to the bottom of.

The mcsMusic plugin was my first published application using xAP. In that manual there is a description of what needed to be done to use the SliMP3 with mcsMusic via the xAP connector for SliMP3.

There have been people who I held their hand through a setup and integration process and asked if they would document the process for others but it has not come to pass.

When I started I joined the Yahoo developers group for xAP. When I changed email address I never rejoined. It is a good forum to get support for the works that are described in xapAutomation.org. Everything you tried is from that location.

To use Homeseer and xAP together you need an xAP plugin and for all practical purposes a hub on each computer on which an xAP application is running. You can get James' plugin from this Message Board and Stuart's hub from xAPFramework.net. The xAP Viewer from Stuart's site is also an essential tool so you can observe the message traffic.

In my case I use mcsXap as the Homeseer plugin and mcsxapHub for the hub. I have provided these to those that have a need.

xAP Conduit tries to be a plug'n'play solution to allow Homeseer participate in an xAP environment. If you are comming from xAP to Homeseer then this is what you want. mcsXap's goal is to virtualize the plugin Homeseer interface and uses xAP as the mechanism to do this. If you are starting with Homeseer and want to distribute some of your computing or interface to a specific xAP connector then this will be a more natural plugin to use.

I've experienced problems with message replication and with messages being echoed back to the sender using the xapFramework.net suite of hubs. Another objective of mine is for managed redundancy in the system and a hub is too iimportant to leave it alone without a backup. This is why xapmcsHub was created. I also dabbled with xPL and xapmcsHub also served as a gateway from xPL to xAP as it served as both an xAP and xPL hub and translated the schema of interest between the two protocols.

Many of the applications pointed to be xapAutomation.org will startup and grab the xAP-reserved IP port 3639. This will prohibit a hub from doing its job. When using these application make certain you launch the hub first. The applications I post assume a hub will evenually startup and will not be able to receive xAP messages until the hub does start. The downside is that a PC that has only one mcs xAP connector will still need a hub.

My entire HA environment is now distributed with mcsXap, WebAgent and mcsMovement the only plugins installed with Homeseer. In the process I took several roads that were dead ends because the end result was awkward or did not achieve my objective. This means that things change often. I do post xAP nodes at http://board.homeseer.com/forumdisplay.php?f=747 that I feel may be useful and relatively stable. These will continue to change, but the core functionality should remain intact.

One should start by identifying an xAP connector that is of interest or by having a need where distrubuted computing will provide an elegant solution. I think a shotgun approach will be frustrating. It would be like ordering a bundle of parts from X10.com and then trying to figure out what to do with them. SliMP3 with mcsMusic is an example. UPB interface is another. Messages on MCE is another, use of the Windows desktop for a HA display device or integration with XLobby is another.

The core shopping list is:
1. Microsoft .NET 1.1 framework
2. xapFramework.Net GUI Message Viewer
3. One of three hubs from xapFramework.net or xapmcsHub
3. xAP Conduit or mcsXap Homeseer Plugin

Everything beyond this is optional. If nothing else is added then one will be able to run the Viewer and observe the heartbeat messages and any xAP messages that have been mapped into Homeseer virtual devices.

Once you get past the infrastructure then the next situation that will arrise is that a system context needs to exist for things to be very useful. If you have a MCE, TIVO, SliMP3 or Audrey connector that can display messages you will need something that will send the messages to display. For most Homeseer users this will be coordinated out of Homeseer as events. As your system becomes more distrubuted then there will be more peer-to-peer messages occurring. For example, my road lights are controlled by motion and is sensitive to sunrise/sunset times. The sunrise/sunset info is distrubuted periodically and the motion sensor activity is put on the LAN when it happens. The UPB connector sees the motion, knows if it is nighttime, and then sends the command to the road light. The change of state in the light goes onto the LAN. Homeseer also receives the motion indication and will see the new state of the light and can do things with it, but the important/time-sensitive loop will be done without Homeseer. The only conceptual thing that changed from my setup last year vs this is that the script that controls the light was running under Homeseer control while now it is running as part of the UPB connector.

You will also experience some understanding problems with the xAP plugins. It is my understanding that xAP Conduit understands the Basic Status and Control schema and will interpret it for use within Homeseer. The other schema just look like Greek to it so it can do nothing more than stuff the words into a virtual device. Quite often this is adequate for display and trigger purposes. mcsXap understands a specific set of schema that would naturally be used by Homeseer. X10, IR, and Basic Status and Control are mapped into the three Homeseer interface types available to the SDK. If Homeseer sends it as X10 then mcsXap virtualizes it as xap-x10. If Homseer sends it as an IO interface then mcsXap virtualizes it as xapbsc. The same is true in the opposite direction. A typical Homeseer IO interface will present the user an enumeration of control options. mcsMusic, for example, will allow a user to select play, pause, stop as a virtual device control. I wanted to maintain this same desirable user interface so I extended the xapbsc schema to support it. As an extensioni it will not interfere with other xAP connectors, but the other ones, such as xAP Conduit will not understand it so the list of control options will not be presented.

[garygfx]

You've provided yet another great insight, thank you. I think I need some more devices worth controlling. I've got lights, a security system, fans and a mp3 player (still haven't been able to try mcsMusic!) but not much else. I've got lots of devices that provide an input which I can see xAP using to alert me to things via my desktop.

As I'm curious, could I have a play with your xapmcsHub and mcsXap apps please?

[Rupp]

garyfx,
You have hit the nail on the head with your excellent observations. There are simply too many "pieces and parts" for the user to want to dig into. This is why many users use Christians message server and client to do just what you describe, as in getting messages from one machine to another without the difficulty of loading a desperate set of apps that are a bit difficult to discern and use. I've tried a couple of times setting up this xAP stuff but lost my train of thought that was about 20 minutes long.

[Michael McSharry]

I had a need and saw a value in seamless distributed computing. I could have gone down the road of yet another special purpose set of applications to do specific functions (e.g. MessageServer, mcsMusicServer, Girder, HS2 Remote Speaker), but I elected to take the road of a supported standard that covers the entire spectrum of HA-related computing.

Until one has a need there is little reason to pursue xAP, JAVA, VB, or any of the other multitude of computing technologies that are out there. There are lots of sandboxes to play in. Some even sport sandcastles for those that need their kingdom.

Gary, I'm willing to share my xAp applications, but I'll wait until there is something that you want to do that makes these attractive. I got started about 18 months ago with the concepts that I published at http://board.homeseer.com/showthread...ed+environment. Things have changed as I learned, but the vision is still valid. The writing also reflects a very novice view of xAP and how to get started with it. Over this time I have become more savy with it and distributed computing in general. When TVs, Toasters, and Dishwashers start communicating in an intelligent manner it will not be xAP, but the issues of how to effectively manage all these little computing entities will be the same as I'm experiencing with xAP integration.

[garygfx]

Because of a lack of a good beginner's guide I don't think most people realise what they can do with xAP until they've installed a handful of xAP components and played around with it.

I agree that usually you'd only employ a technology if you first have a need for it, but usually you'd first learn about the technology to see if it offers anything beneficial. This isn't possible with xAP since the lack of a decent beginner's guide prohibits a lot of people from firstly getting involved and secondly making any headway.

Michael, the document that you pointed me to goes into a fantastic amount of detail, I'm impressed with the effort to document xAP and your tools (it's better that the documentation of some of the IT projects I've been employed to work on!) but it's a technical introduction as I'm sure you realise. Why someone hasn't duplicated your efforts and produced a consumer's or enthusiast's introduction I do not know.

I'm sure your xAP tools are really good but by keeping them from the average user they're denied the chance to get into xAP and experiment with better/other tools. Sure, you have every right to keep your work private but it's like having a Rembrandt in a private collection!

As a journalist I'd be very happy to write a beginner's guide to xAP for the Public Domain since I won't be duplicating any existing efforts. But until a reasonably competent person likes me can get to grips with what's on offer from xAP there will never be a take-up of xAP outside of the xAP development community. Like my Rembrandt in a private collection analogy, this is a shame since it's something the public would really enjoy given what I've learnt about xAP in the past 24 hours.

Rupp - glad you agree, but how do we get the xAP developers to realise there's a problem? If they're happy with it being a closed community then I'll "zip it" [Dr Evil], sit back down and apologise for making a fuss.

[TrOjAn]

I would just like to add my voice to this thread in so much as I too have played around with xAP now, I downloaded every type of xAP software I could find, I had a hub running on every pc on the lan and various programs.. they all seem to talk to each other but apart from that.. what to do?

In particular I was interested in the xAP Speak program which implies you can type speech into one lan pc and have it played / read on another.

I planned on using this to enter text on the laptop to have HS speak it over the house speakers.

Unfortunatly I couldnt work that out either

An idiots guide to just get ANYTHING working would, Im sure, get lots of people interested.. it sure looks impressive

[Rupp]

Rupp - glad you agree, but how do we get the xAP developers to realise there's a problem? If they're happy with it being a closed community then I'll "zip it" [Dr Evil], sit back down and apologise for making a fuss.

Ahh if we only new the answer to this, think of the software we could get out of the dark corners of PC's around the world and into the main stream. Here in-lies the problem, where brilliant types like Michael and others know what it takes to paint that Mona Lisa but, are too brilliant to talk in simpleton terms (not that they would want to or need to). The epiphany that is xAP is amazing thing. The uses are limitless but applications seem scattered and uncontrolled which leads us simpletons with short attention spans looking for the next quick fix.

[garygfx]

Yes Rupp, a good summary. As co-chairman of the Luddite's committee I agree that we're lacking the technological experience in the field that the xAP programmers have to fully comprehend, appreciate, and utilise xAP in the same way that they do.

Our committee would like to produce a Luddite's guide to explain all but we're unable to teach our members when we don't know much ourselves.

I would write a guide this afternoon to bring others up to the same point where I'm at now (the basics are installed and things are talking but half the stuff doesn't work and I don't know what to do next). But this isn't any good if I can't part the Red Sea and make our way over to the promised land. I'm stuck between a rock and an ocean.

Michael, I don't have any contact with the other xAP guys but if you could kindly mention some of our thoughts to them we'd all be grateful. Even if they can only translate the Martian to Greek then I could make an attempt to translate the Greek to English!

Ideally an article like this would be brilliant:

• What is xAP (an excellent but simple* explanation)
• What can you do with it? (practical examples)
• What you need to use it (computers, LAN, software)
• Getting started (a walkthrough guide explaining what to download, where from, and how to configure it)
• Example scenarios (a walkthrough guide to set up a couple of useful xAP apps for a practical purpose)
• Troubleshooting (what could go wrong and how to resolve issues, firewall configurations, etc)
• The future (what's in development and where all this is going)

* "simple" in this case means what the average HA user would comprehend which is on a different level to what (xAP) programmers would define as simple. I think that's half the problem. xAP doesn't have a commercial arm to ensure things are explained properly. Linux suffered the same problem in that the developers and hard core users thought it was straight forward but it's almost alien to everyone else. Commercial Linux developers are slowly making it more comprehensible but still have a long way to go. I've digressed, sorry.

Gary.

[Rupp]

Gary,
Watch it now. This is starting to sound like a xAP for Dummies. These books do sell well you know.

[Michael McSharry]

HTTP is the mechanism used by Internet Web Servers and PC Browsers to communicate. A typical Browser user has no need or desire to understand HTTP. They simply want to use the Browser as they would any other application running on their computer.

The instant you take the step of "what is xAP" then you have moved from the user domain to the developer domain. It is sufficient to say that xAP is to distributed automation as HTTP is to web surfing.

There are some pretty spiffy web pages out there that yield a positive user experience. There are some others that leave the user wanting. There are some Homeseer plugins that are intuitive, some that are complex. Some work for most users. Some just are not worth the effort to understand. xAP applications are no different in their spectrum of value to the user.

For something to be called xAP it simply means that one of its features is the ability to understand the xAP protocol. It is like the requirement for anything that is called a Browser needs to understand HTTP.

One of Homeseer's selling features is its abiltiy to interact with many different pieces of equipment. HST defined an SDK to provide the communication interface. My xAP/Homeseer activity simply uses the Homeseer SDK interface and puts an extension cable between Homeseer and a Plugin. The extension cable is the LAN. Nothing has changed except the Plugin does not start and stop when Homeseer starts and stops and the Plugin can run on any computer that is on the LAN. xAP is the language I use to communicate over the LAN between Homeseer and the now-disassociated plugin.

Since plugin A and plugin B both are on the LAN and both use xAP as the language they are able to communicate amongst themselves if they so desire. Nothing forcing them to play together. At the start of a basketball game the players are all on the field and all shooting hoops together during warmup. There is some entertainment value in watching this, but one appreciates watching more when the players work as a team and build upon each others strengths. There is a coach to provide overall guidance, but the real action is with the players working together.

Before long names like Ming and Divac starting showing up. They did not start their lives as Homeseer plugins, but they did understand xAP so they were invited to play and make good contributions to the team. As more showed up it became hard to distinguish the original Homeseer-bred plugin from the others.

--------------------
Under HS2 one does remote VR and TTS by installing HS2 in computer A and the HS2 Speaker Application on computer B. There is some configuration that needs to be done to make the two nodes do what you want. What you have got are two applications that are using the LAN to communicate. They talk their own language and it is specialized to do just Homeseer audio functions. You will not see a third application that will be joining the mix.

Under HS1 (or HS2) you can install the mcsXap plugin. Refer to the Homeseer documentation on how to install a plugin. On a second computer install xapmcsVoice. It is posted in the mcsPlugins/xAP subforum. Two setup items are needed. In the mcsXap plugin the checkboxes to speak via xAP and Remote VR need to be checked. In xapmcsVoice the path to the Homeseer grammar file needs to be entered. The full LAN path to the Homeseer grammar path is needed so same phrases will be understood by the remote node as the local one.

The infrastructure also needs to exist.

In the case of HS2, the .NET framework and SAPI5 is needed. HST bundled these with their intaller. Together they are on the order of 50 Meg.

In the case of xAP SAPI5 and an xAP hub is needed. SAPI5 is obtained from Microsoft's download site. xAP hubs are available from multiple sources. I'll attach one for simplicity. Both SAPI5 and the xAP hub need to be installed on every computer using xapmcsVoice or mcsXap.

SAPI5 provides services so no special startup is required under either scenario. The xapHub, the remote speaker application, xapmcsVoice, and Homeseer all need to be started on each computer where they are intended to run. This can be the startup folder or manually as you desire.

On any computer where VR is used there needs to be a microphone and audio input interface. On any computer where TTS is used there needs to be an audio output interface and some form of speakers.

[TrOjAn]

Michael, many thanks for your response... the 2 pictures and the walk through is great.. Im halfway there, will finnish it tomorow, thanks again

TrOjAn