ORG-Link

General purpose serial link tool.

For all variants of Psion series II Organiser.

ORG-Link.zip Size: 36,124 bytes.
CRC32/MD5 codes: 2EE6EBDC/522314EFD7907831C869D4F840A30EB2.

Compatibility and context:

ORG-Link exists to replace the Psion programs CL, Make, and Unmake and many of the files that went with them. It avoids difficulty with file paths and access to the serial ports that DOS-based command line programs have in a Windows operating system. Even if the access was possible, any other activity on the computer (even some small unexpected event or scheduled activity), would demand time from the CPU, cause stalling in the serial data flow, and time out, leaving another 40-minute wait for a UV formatter to make the data pack reusable! Something had to be done to remove this source of pain. Psi2Win was written for the same reasons, but ORG-Link is much smaller and does a lot more. It was written in C using Win32 API calls, so it would work even on the leanest and smallest embedded Windows OS if that OS could use a serial port.

The FTRAN and FILE modes (Psion called them 'overlays') are fully supported. EXIT is not, it is ignored. ORG-Link is a server, it's going to sit there ready until the user stops it directly by acting on its own panel. Given that it's extremely likely that anyone linking the Organiser and a computer will be able to reach both machines, this is wise because if the Organiser says 'EXIT' it can never cause the remote end to be ready for more work.

BOOT mode is also fully supported, but is extended to combine many other functions and make them all equally easy and fast to use. To use any of them, the method is to start it by a click of a button on ORG-Link, then browsing for a file if needed, then selecting BOOT from the Comms Link menu on the Organiser and pressing Enter. It will ignore any filename entered and use the inbuilt boot code for the requested task. Watching both machines as the process occurs will make it very self-explanatory what to do, and what is happening when you do it. If you have a external boot file, you can ask for it by name at the BOOT prompt, and you will get it in the normal way if you have put it in the same directory as ORG-Link so it can find it. Once an action is started, all controls except the emergency stop button, and the standard Windows control buttons, will be disabled until the action is completed, to prevent accidents during a transfer. Visual cues to the current state are given, with more detail than CL or any of the other programs would give.

ORG-Link controls:

The toolbar has four tool buttons, two port setting controls, and a connection state indicator. The settings are best left to their defaults even if you know what you are doing, unless you have a specific reason for changing them. Port numbers range from 1~64, which is likely enough to find one on a system with lots of virtual or USB ports already in use. The Baud setting should be as fast as possible, and must match the value selected by the Organiser's Comms Link setup.

Check that the connection state indicator glows green, that the chosen port is linked to an Organiser, that the Baud settings match, that the Psion protocol is enabled in the Organiser, and that your hardware and power are in good order.

Of the four toolbar buttons, the first two replace the RECV and TRANS methods provided with CL. They work with pack A, the internal memory. They save and restore top level menus (except where bootable code manages its own menu entries), along with files, alarms, diaries, calculator memories, sounder mute state, and a few other useful details. Unlike the original tools, ORG-Link will allow you to name the files and locations used for your backup files. Just remember that they MUST be reserved for use with the same type of Organiser, ideally the SAME Organiser, to work properly, but this is a very effective way to clone a system across multiple machines of the same type. This does not extend to imaging 'allocator cells' and installed resident machine code programs, but in future it might because it's definitely possible to write code to extend these methods to do it.

The Clock button will set the time and date on any Organiser 2 machine. It uses a method that all of them support, and it is deliberately designed for consistency, i.e. 24-hour mode on all machines, and no 'daylight saving' time. This is to make it extremely easy to know what it will do. If your computer is set for local time, daylight saving time, correct locale, etc, then you have the time as you need to see it. The time sync tool in ORG-Link makes sure that what you see is what you get. By using it, you get the exact same time displayed on the Organiser.

The Emergency Stop button is designed to let you stop boot code transfer and restore the standby state so ORG-Link will quickly respond to user input if something goes wrong, or 'hangs', or if you just changed your mind in mid-progress. Wherever possible it will do the same for the Organiser at the same time. This detail removes a lot of the inconvenience associated with use of the original tools. It signals the Organiser in a way that causes the most graceful exit possible with existing code, and will not result in data loss or other disturbance. There may be conditions where it will not work, and you'll have to force the program to terminate, but if that needs to happen there are probably more serious problems that are hard to predict or set up on purpose for testing. If this happens, check the hardware. High baud rates with extra long cables, or unusual DIY connections can sometimes cause such errors by totally confusing the system with malformed bytes. If you have good connections and power, this is very unlikely to go wrong.

The four large buttons do exactly what the text on them says. Their actions replace the Psion MAKE and UNMAKE pack handling tools, and replicate their action precisely, but with two vital differences: 1, Psion limited this to pack C only, but with ORG-Link you can select pack B if you want, avoiding the need to risk physical and electrical stresses by moving packs when you don't want to; and 2, there is no 'AMAKE', you cannot append to a pack other than copying files to it in the normal way. It's much easier, and safer, to make a clean pack image in one go.

ORG-Link config:

The config file is automatically generated the first time ORG-Link is run, if it is not there already. The image below shows the defaults made when it was started in the directory where this web page was written.

The config file stores many useful things to make it easy and comfortable to work with for long periods, or to recall a working state so that months or years after using it, you can immediately see how it was last set up. This can help enormously when working with old code because context like that helps memory. It makes the difference between fighting unfamiliarity, or getting support from known past conditions. Even the colour scheme can be changed so if you have problems with vision it can help you (and a dislike of my chosen colours need not prevent you from using it). It will remember where you put it onscreen. If you ever want to put it dead centre, first put it so its top left corner is beyond the top and left of the screen, then close it. Next time it runs, it will be centred.

Some details will need direct editing of the config file. An obvious one is the interface colour editing. Another is the path to the directory where you want files transferred by FTRAN or FILE modes to go. It defaults to the base directory where ORG-Link goes, but can be elsewhere.

TermChar, if set to 1, adds a final character (ASCII code 26) to OPL files so they will work cleanly when transferring them back via the Comms Link menu. If set to 0 it will not add the character. Either way, the file transfer will work with the Psion protocol (binary), but if receiving OPL files with ASCII (text) transfers, the termination character allows the Organiser to know automatically when transfer is complete, so if you want files to be transferable with any terminal emulator, leave TermChar set to 1 when transferring them to the computer using ORG-Link.

BootTest is extremely useful if you're experimenting with Organiser machine code called from a computer. DO NOT do this on an Organiser than wasn't freshly powered for this activity! Data loss WILL happen. If you know the territory you won't need this warning, but the aim of ORG-Link is to help those who are not familiar, to get there easily. What BootTest does is bypass the checksum tests in ORG-Link (the Organiser does not do these tests), so you can write and edit code without worrying about the checksums. When BootTest is set to 1, ORG-Link tells you those on its title bar. Ignore them till you need them, then copy them to the correct positions in your code, reset back to 0, and your code (and the Organiser) will be protected against accidental corruption as usual.

Last words:

The external tools needed to support use of ORG-Link are few, but vital. Most if not all are command line tools, but as they are limited to local file activity they will not have trouble with port accesses in Windows, the likes of which ORG-Link exists to solve. These tools are OPLTRAN.EXE or ATRAN.EXE, to translate OPL code to OB3 files which contain compiled code and optionally the OPL code too. BLDPACK.EXE and SPLITOPK.EXE are needed to make pack images from these files, and to restore individual files from pack images once made, or after ORG-Link has read the pack. With a few boot files and some effort with machine code, there is likely nothing on a Psion Organiser that you cannot do with this method. The deeper you go, the more you'll need the documentation to help you, but it's all available, either from Jaap Scherphuis' site, or from Boris Cornet's site. Styles differ but they share a lot of content in common. These Psion machines are unusually well documented! Psion XP and LZ emulators exist, but they do not emulate the Hitachi CPU's machine code, or any of the low level hardware access methods. ORG-Link was designed to make using a real Organiser easier than using the emulators, using all that a modern computer can do to help make the best of the Organiser itself, because those machines will always be a standard to judge all others by, in terms of power to do things while demanding very little in order to do them.