Tim Long

ASCOM Platform 5.0 class diagram

I just threw together a diagram of all the various interfaces, classes, enums and structs that are defined in the new ASCOM Platform 5.0. I thought it might be useful as a quick reference card. The diagram is attached to this post both as an XPS (XML Paper Specification) document - the express versions of Visual Studio can't display class diagrams so I used XPS, which should render on all up-to-date Windows systems. If you'd like a copy of the class diagram (.cd) file, drop me an email.

Oh, if you can't see the attachment then you need to click on the article title, above. Then look for the attachments in the little cluster of hyperlinks at the bottom.

Caveat: this is based on alpha 3 and might change before final release.

Symantec in Cardiff

Symantec are putting on a free "Sales and Technical Open Day" event in Cardiff tomorrow, Wednesday 30th May at the Hilton hotel on Kingsway. I've only just found out about it and will probably try to attend. Attached is the agenda (PDF).

The Office Live Opportunity

I've just been helping a friend get his business, Interesting Places, set up on Office Live. I'm quite pleased with the results - especially as it didn't cost a penny. He has his own domain name, email and a web site that should be easy to maintain without any special knowledge other than the ability to type.

TiGra Networks is a UK Office Live partner and we're offering free basic web design to get new businesses online quickly and cheaply. Of course, we don't make any money from that, but it enables us to meet new potential clients and start building trust. Hopefully, they'll realise that we are not going to rip them off and they'll come back to us for all their IT business in the future.

By the way, if you're feeling stressed and need a weekend away from it all, why not book a weekend break in Wales with Interesting Places and recharge your batteries on the Welsh mountain air?

The Seventh Habit

Are you familiar with Steven Covey's "The Seven Habits of Highly Effective People"? My favourite habit is number 7, Sharpening the Saw. It's an area that I think a lot of people neglect - particularly in the IT industry. Sometimes we're all so busy doing stuff then suddenly we look up and realise the world has moved on. I think the perennial hardware vs. software firewall debate is an example of this, to some extent.

It is important to sharpen the saw in four dimensions: Physical, Spiritual, Emotional and Mental.

If I have a fault in this area, it is that I tend to over-indulge myself in mental saw-sharpening sometimes at the expense of actually doing anything productive. Saw sharpening is such fun, and fun is an addictive drug, my friend. There is a balance to be struck, though; that's why we need to engage in beta programmes and try to stay ahead of the game. I aim to spend at least a day a week trying out new things and just letting new technology wash over me.

Lately I've come to the realisation that I've been neglecting my physical saw. Hence the reason I've resurrected my mountain bike. I must look fairly odd wobbling along in my lycra - I even got a wolf whistle from a group of young lads yesterday! That probably wasn't a compliment, but I take comfort in the knowledge that I am sharpening my saw while they, in their impetuous youth, have not realised yet that they even have a saw and that it needs sharpening.

Don't wait until your saw is blunt or broken. It is a lot easier to keep a saw sharp than it is to let it wear out then try to fix it. A saw can be discarded and replaced - not so a human body. If you have children, perhaps one of the biggest services you can do for them is to introduce them to your local scout group or volunteer cadet corps. The experience will give them the toolkit they need to sharpen their saw in later life.

The Art of Arithmetic

There are only three types of people: those who can count and those who can't. According to LinkedIn.

 To be fair to LinkedIn, this condition only persisted for a few minutes. On a more serious note, I've been playing around with LinkedIn for a few months now and I'm finding it a lot more useful that I thought I would. They've just released a new version of their Outlook Toolbar which now works in Outlook 2007 and is actually a very well produced piece of software. I've got hundreds of contacts and LinkedIn helps me keep them all up to date. It also helps me stay in touch with former work colleagues and track them as they change jobs, etc. and I can see lots of potential future uses for this web 2.0 business networking tool. Best of all, I've never had a single piece of spam as a result of being a LinkedIn member.

If you have a spare moment, go check it out. You may be surprised how many of your colleagues are already members. Visit my public profile and join my network. My profile is 95% complete and I need another recommendation to take that up to 100% (hint, hint...)

I'm back (from the dead)

As my caving friends sometimes say to me, "I've been a long time dead". Having fixed up my mountain bike last week, I finally took it for a tentative test drive today, a staggering 1.2 miles. Not as hard as I expected, either, though 1.2 miles is not even enough to go aerobic (I seem to remember it takes me about 15-20 minutes to fully gain my second wind).

This short sojourn was really to kick the tyres and see what fell off. The bike is actually doing remarkably well. The chain is too slack, though it is the right length so the rear deraileur probably needs tweaking up a bit.

Next time out: target 5 miles on the flat.

ASCOM Driver Diagnostics

With the upcoming release of ASCOM Plaform 5.0, .net developers will have a whole new arsenal of tools at their disposal. The project templates for drivers provide a great head start when embarking on development of a new driver. However, there is very little in the way of diagnostics to help debugging and troubleshooting both during development or in-the-field. In this article I present a simple yet powerful technique for including flexible diagnostic tracing in your ASCOM driver, both during development and for troubleshooting in-the-field.

Historically, most ASCOM drivers have relied on the serial communications classes included in the Helper.dll component. This provided tracing of the serial protocol which could be enabled on demand by editing a registry key. This was great as far as it went, but was limited to tracing of the serial data and would not be available if a different serial communications library were used.

In future, most drivers will be developed in Visual Studio and will target the .net Framework, which contains powerful diagnostic tracing tools. The technique presented here relies on the classes found in the System.Diagnostics namespace, including System.Diagnostics.Trace and System.Diagnostics.TraceSwitch.

Diagnostics.cs

Lets dive right in with the code for a few helper methods to make diagnostic tracing easier. The following code can be found as an attachment to this article, so you can quickly download it and begin using it in your own projects:

using System;
using System.Collections.Generic;
using System.Text;
using System.Diagnostics;

namespace TiGra.Astronomy
{
    /// <summary>
    /// The Diagnostics class provides a few helper methods that make it easier to produce coherent
    /// debugging output. The class is implemented as a singleton that is created as soon as the assembly
    /// is loaded. The level of trace output that is produced is controlled by a <see cref="TraceSwitch"/>
    /// that in turn loads its configuration from the App.config file. If there is no App.Config file,
    /// the default is to produce trace output for errors only.
    /// </summary>
    internal class Diagnostics
    {
        static private Diagnostics theOne = new Diagnostics();    // Don't defer creating the singleton.
        static TraceSwitch ts;

        protected Diagnostics()
        {
#if DEBUG
            ts = new TraceSwitch("TiGra.Astronomy.MyDriver", "TiGra.Astronomy.MyDriver", TraceLevel.Verbose.ToString());
#else
            ts = new TraceSwitch("TiGra.Astronomy.MyDriver", "TiGra.Astronomy.MyDriver", TraceLevel.Error.ToString());
#endif
            Trace.WriteLine("===== Start Diagnostics: TraceLevel = " + ts.Level.ToString() + " =====");
        }
        /// <summary>
        /// Gets a reference to the one and only instance of this singleton class.
        /// </summary>
        /// <returns>a reference to the one and only instance of this singleton class.</returns>
        public static Diagnostics GetInstance()
        {
            if (theOne == null)
                theOne = new Diagnostics();
            return theOne;
        }

        /// <summary>
        /// Send an object to the trace channel at severity level Error.
        /// </summary>
        /// <param name="msg">The object (which may be a string) to display.</param>
        static internal void TraceError(object msg)
        {
            Trace.WriteLineIf(ts.TraceError, msg, ts.Description + "[Error]");
        }
        /// <summary>
        /// Format and send a list of objects to the trace channel at severity level Error.
        /// </summary>
        /// <param name="format">Format string used to format the objects.</param>
        /// <param name="items">List of objects to be displayed.</param>
        static internal void TraceError(string format, params object[] items)
        {
            Trace.WriteLineIf(ts.TraceError, String.Format(format, items), ts.Description + "[Error]");
        }
        /// <summary>
        /// Send an object to the trace channel at severity level Warning.
        /// </summary>
        /// <param name="msg">The object (which may be a string) to display.</param>
        static internal void TraceWarning(object msg)
        {
            Trace.WriteLineIf(ts.TraceWarning, msg, ts.Description + "[Warn]");
        }
        /// <summary>
        /// Format and send a list of objects to the trace channel at severity level Warning.
        /// </summary>
        /// <param name="format">Format string used to format the objects.</param>
        /// <param name="items">List of objects to be displayed.</param>
        static internal void TraceWarning(string format, params object[] items)
        {
            Trace.WriteLineIf(ts.TraceWarning, String.Format(format, items), ts.Description + "[Warn]");
        }
        /// <summary>
        /// Send an object to the trace channel at severity level Information.
        /// </summary>
        /// <param name="msg">The object (which may be a string) to display.</param>
        static internal void TraceInfo(object msg)
        {
            Trace.WriteLineIf(ts.TraceInfo, msg, ts.Description + "[Info]");
        }
        /// <summary>
        /// Format and send a list of objects to the trace channel at severity level Information.
        /// </summary>
        /// <param name="format">Format string used to format the objects.</param>
        /// <param name="items">List of objects to be displayed.</param>
        static internal void TraceInfo(string format, params object[] items)
        {
            Trace.WriteLineIf(ts.TraceInfo, String.Format(format, items), ts.Description + "[Info]");
        }
        /// <summary>
        /// Send an object to the trace channel at severity level Verbose Information.
        /// </summary>
        /// <param name="msg">The object (which may be a string) to display.</param>
        static internal void TraceVerbose(object msg)
        {
            Trace.WriteLineIf(ts.TraceVerbose, msg, ts.Description + "[Verb]");
        }
        /// <summary>
        /// Format and send a list of objects to the trace channel at severity level Verbose Information.
        /// </summary>
        /// <param name="format">Format string used to format the objects.</param>
        /// <param name="items">List of objects to be displayed.</param>
        static internal void TraceVerbose(string format, params object[] items)
        {
            Trace.WriteLineIf(ts.TraceVerbose, String.Format(format, items), ts.Description + "[Verb]");
        }
        /// <summary>
        /// Utility function. Expands non-printable ASCII characters into mnemonic human-readable form.
        /// </summary>
        /// <returns>
        /// Returns a new string with non-printing characters replaced by human-readable mnemonics.
        /// </returns>
        static internal string ExpandASCII(string strTrace)
        {
            StringBuilder expanded = new StringBuilder(Math.Max(64, strTrace.Length * 3));
            foreach (char c in strTrace)
            {
                byte b = (byte)c;
                string strASCII = Enum.GetName(typeof(ASCII), b);
                if (strASCII != null)
                    expanded.Append("<" + strASCII + ">");
                else
                    expanded.Append(c);
            }
            return expanded.ToString();
        }
    }
#pragma warning disable 1591    // No XML documentation is required for this enum
    /// <summary>
    /// Byte type with enumeration constants for ASCII control codes.
    /// </summary>
    public enum ASCII : byte
    {
        NULL = 0x00, SOH = 0x01, STH = 0x02, ETX = 0x03, EOT = 0x04, ENQ = 0x05, ACK = 0x06, BELL = 0x07,
        BS = 0x08, HT = 0x09, LF = 0x0A, VT = 0x0B, FF = 0x0C, CR = 0x0D, SO = 0x0E, SI = 0x0F, DC1 = 0x11,
        DC2 = 0x12, DC3 = 0x13, DC4 = 0x14, NAK = 0x15, SYN = 0x16, ETB = 0x17, CAN = 0x18, EM = 0x19,
        SUB = 0x1A, ESC = 0x1B, FS = 0x1C, GS = 0x1D, RS = 0x1E, US = 0x1F, /*SP = 0x20,*/ DEL = 0x7F
    }

}

The first thing to notice is that the Diagnostics class implements the Singleton pattern. The constructor is protected so no instances of this class can be created, other than the one default instance that is created during program initialisation. The class includes a TraceSwitch, which controls the amount of detail that will be produced in the trace output.

Trace Levels

A TraceSwitch defines four levels of detail: Error, Warning, Information and Verbose. For ASCOM drivers, the convention I have adopted for each trace level is as follows:

1. Error - used to display exceptions and unrecoverable errors.
2. Warning - used to display recoverable errors (for example protocol timeouts and re-tries) and other unusual or unexpected conditions that need to be highlighted.
3. Information - Entry and exit into the various properties and methods of the driver, argument values and property return values.
4. Verbose - detailed information about the inner workings of the code, including contents of transmitted and received packets.

The TraceSwitch is initialised differently for Debug and Release builds. During debugging, full verbose tracing will be enabled. In contrast, the default for release builds is to trace only error conditions. Whatever the default setting, the trace level can be overridden by creating or editing an App.config file (more on that later).

Methods

The Diagnostics class defines two methods for each trace level. The signatures look like this:

static internal void TraceXXX(object msg)

static internal void TraceXXX(string format, params object[] items)

These are repeated four times, with XXX being replaced with the trace level in each case. The first form is useful for displaying any object value in the trace output - note that a string is also an object, so this form is useful for displaying arbitrary text, thus:

Diagnostics.TraceError("Exception interrogating firmware version:");

The second form is more flexible and works exactly like String.Format() - it takes a format string and a list of objects to be formatted. Here's an example:

Diagnostics.TraceVerbose("Writing AWR register {0}={1}", address, data);

The final method is ExpandASCII() that replaces non-printable characters in a string with their ASCII mnemonic, so ^G (control G, ASCII 0x07) would be replaced with "<BEL>". This can be useful when displaying data received from the device.

Using The Diagnostics Methods

Simply include calls to the 8 static Diagnostics.TraceXXX() methods throughout your code. Which method you use is dictated by the severity of the information you want to display - refer to the guidance above under "Trace Levels" when deciding what level to use.

Controlling The Trace Level

The default trace level is set in the code by the following lines:

#if DEBUG
            ts = new TraceSwitch("TiGra.Astronomy.MyDriver", "TiGra.Astronomy.MyDriver", TraceLevel.Verbose.ToString());
#else
            ts = new TraceSwitch("TiGra.Astronomy.MyDriver", "TiGra.Astronomy.MyDriver", TraceLevel.Error.ToString());
#endif

This gives full tracing during development and minimal tracing for released code. However, there may be times (for example when needing to provide technical support to an end user) that the amount of trace information needs to be increased or decreased. This can be done by creating an App.config file, or editing an existing file, and adding the following entry in the <configuration> section:

    <system.diagnostics>
        <switches>
            <add name="TiGra.Astronomy.MyDriver" value="4"/>
        </switches>
    </system.diagnostics>

Notice that the name (name="TiGra.Astronomy.MyDriver") corresponds to the name used in the TraceSwitch declaration in the code. You should change both to reflect the name of your driver's assembly file. The value attribute sets the trace level, where 1 produces the minimum amount of trace output (corresponding to Error level) and 4 produces the most output (corresponding to Verbose level).

Advanced Tracing

Trace output normally appears in the Visual Studio Output window. But what if you need to trace code running on a user's computer, or one where Visual Studio is not installed? What then? Enter SysInternals' DebugView. With DebugView, you can capture trace output without requiring a debugger to be installed. It also provides tools for filtering and colourizing your trace ourput to make it easier to read, and allows you to save trace data for later analysis. Using DebugView, an end user can capture a session's trace output and email the file to you for analysis. Or, if you have a network connection to the end user's computer, DebugView can be used in a special client-server mode where trace output is sent accross the network and can be viewed remotely in real time.

I use DebugView's client-server mode when I'm debugging my drivers. I run the driver inside Visual Studio and I run DebugView on a laptop computer so that all the diagnostic output is sent to the laptop screen, leaving my main screen free to examine and debug the code. The screen shot shows an example of DebugView in use - note the colour coding and time-stamping of each line of output.

I'm Only A Small Business Specialist

 Today I was talking to someone about Microsoft certifications. The conversation went something like this:

My friend has just become a MCSE.

Oh, that's good. I'm an MCP and Small Business Specialist.

Really? Is that better than an MCSE?

Me: Oh, no. Becoming an SBSC just takes one exam.

I've just seen Susan Bradley's latest blog post, The Symphony of SBS. She reproduces an article by Ofer Shimrat that relates to some other recent posts discussing the idea that SBS might be in its death throws. Ofer's article is worth reading in its entirety because it nicely encapsulates what it really means to be a good Small Business Specialist. Ofer uses the analogy of the Small Business Specialist being the conductor of a symphony orchestra. This passage in particular caught my eye, with my own added emphasis:

Metaphorically speaking, as consultants in the SMB space selling, installing, deploying, implementing and maintaining SBS – we ARE conductors. And as good SBS consultants we are akin to good symphony conductors. We have to know MUCH more than the average MCSE in a single particular area of expertise. There are MANY more fields that we have to have robust knowledge of in order to be considered good at what we do.

On a business level we have to determine the business need, the desired outcome and the methodology to get there. On a technology level we have to master not ONE server product, but SEVERAL server products bundled in SBS. We have to master not ONE piece of hardware but SEVERAL pieces of hardware to corroborate the desired outcome with SBS. We have to master not ONE piece of software but SEVERAL pieces of software in order to make the client machines function PREDICTABLY with SBS – you get the picture.

Yes Ofer. I do indeed get the picture. After reading this article, I realised that being a Small Business Specialist is not so humble. Never again will I apologetically tell anyone that I am "only" a Small Business Specialist.

Dell's Chickens Come Home To Roost

A story on CNet News says that the New York state Attorney General has filed a fraud case against Dell for "false advertising and deceptive business practices, including offering misleading financing, and failing to honor rebates, warranties and service contracts".

It's about time someone had a go at Dell. I've been right on the verge of making a complaint to trading standards on at least three occasions.

Meanwhile, Dell has responded by announcing that it will now sell its computers through third party distributors, ending the era when "you can't buy a Dell in the shops".

It remains to be seen whether IT vendors will want to work with a company with a history of sharp practices.

Support Will Be The Death of SBS, Says Karl

(Via Vijay's blog) Karl Palachuk (whom I met in Birmingham when he was speaking there) is lambasting Microsoft for its weak support for Windows Small Business Server. Obliquely, he blames outsourced support and has instructed his engineers not to call Microsoft Support without express permission to do so! He's also stated that he will not sell SBS in future if there is a viable alternative.

If you're an SBSer you should read his post. Karl is a well known and respected SBSer and his post is a blinder. It is a remarkably frank criticism of Microsoft PSS and something that really ought to make Microsoft sit up and take notice.

I've not yet had occasion to call Microsoft Support on behalf of a customer's SBS. I've used support for non-SBS issues a few times and found it satisfactory. I've also used the managed newsgroups a few times for issues that weren't time critical and found that satisfactory, if a little slow. It is interesting how much variance there is with different people's experiences of Microsoft Support.

Ever Wondered How Your Mouse Works?

All is now revealed. This highly magnified interactive reveals what goes on beneath your mouse cursor. Don't forget to click!

A New Day for Tim

No-one would have believed, in the last years of the twentieth century, I was a fit, active outdoors person. My passions were caving and cycling. Then I injured my knee while caving and moved to America, land of the hamburger. Since then I've been on a slippery slope into increasing weight, decreasing fitness, sedentary lifestyle. A few days ago I turned 43 and with that came the realisation that I'm probably in the last chance hotel if I want to halt the spiral, the only outcome of which can be ever deteriorating health and an early grave. Luckily, I still have my health and I've decided to turn things around before it gets too late.

My trusty mountain bike, a late 90's Marin Bear Valley SE (the era just before suspension became popular) has been sitting out in my garden for the last 4 or 5 years. I decided to break it out of mothballs and press it into service. It is still in amazingly good condition, considering that it has been exposed to the elements all that time. Off with the rust-encrusted rear sprocket and chain. A quick visit to Wiggle.co.uk and a few days later shiny new replacements are in my hands. A few bits of paintwork to touch up where rust spots have formed, everything is now ship-shape and Bristol fashion. Tyres inflated, brakes checked, all the wheel bearings running smooth and true. Deraileurs shifting properly. Bike computer fitted with a new battery. That little computer will make all the difference. First road test (around the petrol station forecourt) completed. Ready for a first expedition.

First time out is going to be really hard. My body is not used to exercise and I have a big pain threshold to cross. But I'm determined to do it.

Ambition: By the end of 2007, cycle the Taff Trail from Cardiff to Brecon. A little over 52 miles of cycle path, mostly off-road following old canals, railways and tramways steeped in industrial heritage. It should be achievable.

Today: >140Kg (my scales refused to weigh me!)

How User Friendly is Your Business Card?

Fancy business cards are a temptation for every business owner. Lately, I've received business cards that vary enormously in shape, size, material, colour and typography. I've even had one card that was completely transparent (printed on acetate). It's only natural to want to impress current and potential new customers. Sometimes it is good to be different to get yourself noticed, but sometimes it is better to just go along with normally accepted standards. Perhaps the design of your business card is one of those times when it is better to stick to convention. If your card is too fancy you may be actually reducing your chance of leaving a lasting impression.

Philip Richardson from the Microsoft Dynamics CRM team posted an article in which he discusses good business card design. He looks at how people use business cards - for example using a CardScan device to enter data automatically - and the implications on card design. He also lists some dos and don'ts for good business card design. My card design, reproduced here, breaks a couple of Philip's guidelines. For example, he recommends printing certification logos on the back. I can't meet that requirements because I print my own cards and the pre-cut media I use does not facilitate duplex printing. I've tried my card in a scanner and ot works pretty well.

So next time you order business cards, spend a moment thinking about how it will be used by the recipient. Consider whether your funky card design will actually make it easy to use.

A New Day in Wales

Yesterday, 3rd May, in addition to being my birthday, was polling day in Wales. We are electing our local and regional AM's (Assembly Ministers). We have a system that goes a little way towards introducing proportional representation (a good thing in my view). Each constituent has two votes. Candidates for each local constituency are elected in a normal first-past-the-post vote and a further 20 seats (4 seats in each of 5 regions) are allocated using the d'Hondt method based on the proportion of votes received by each party (so the last 20 seats are not determined until all of the votes are in and counted).

It looks like the dynamics will be changing. Since the creation of the Welsh Assembly Government a few years ago, Labour had a working majority. Early indications are that will no longer be the case when the result are known in a few hours time. There will have to be some form of coalition and no-one is saying publicly what alliances they have with whom. When the sun rises in a few hours, Welsh politics could be very different.

I think this is a good thing. The political landscape in the UK is stale and no-one cares any more. No-one believes that their vote counts for anything. Today in Wales, this is changing. It looks like we're having quite a high turnout (if you can call the predicted 58% high, I suppose all things are relative). It will be exciting to see how the political power map redraws itself over the coming days.

The first constituency is due any minute now...

A shout out to all those blogging through the election:
Luke Young (Labour); Betsan Powys (BBC Wales); Blamerbell Briefs and others.

When is Free not Free?

Answer: when it is free software.

A few days ago I wrote about "free software" and said that I disliked the terminology. An article on the IMPACT blog looks at the rise of open source software and I'm pleased to note that they also consider the name "contentious".