I wanted to post this months ago, but it seems that long winter breaks have become a tradition on this blog.
In October last year, a reader called DH wrote a comment with his own proposition of a .com-file generator for a bare Portfolio (without any communication interface). His implementation used octal codes instead of hex, but was easier to type in. All you need is to type this at the command prompt (see the original post):
echo /180 ^P /208 /236 /205 ! /168 /223 t ^Q /168 @ u ^U /131 /224 ^O /177 ^D /254 /201 /211 /226 ^A /194 /235 /229 /180 ^B /205 ! 1 /210 /235 /221 /205 [spc] /144 > b8cat.com
where ^P means Ctrl+P, /180 means Alt+1 8 0 when NumLock is on, and [spc] obviously is Space. If you don't make any mistake, you should now have a tool, which will allow you to create executable .com files from octal codes.
DH reverse-engineered DEBUG.COM from MS-DOS 2.0 and put it on Dropbox, so that after re-typing it (remember those listings in computer magazines back in the days?) you'll have this useful tool on your Portfolio.
That's not all. After a while, DH responded again, this time with a hexadecimal-code .com generator:
echo 1 \210 \180 ^P \208 \236 \205 ! \168 @ u ^T \168 [spc] t \242 \168 ^P u ^P \168 ^A u ^X \180 ^B \205 ! 1 \210 \235 \226 ^D ^E ^D ^D $ ^O \177 ^D \211 \226 0 \228 ^A \194 \235 \210 \205 [spc] \144 > b16cat.com
This is a great replacement to h2c.com, described in my post, since it's much easier to type in, it reads hex codes separated by spaces and ignores line breaks (so preparing the input is much easier). Input files must be terminated with "!" (exclamation mark).
Here's MORE.COM transcribed into hex codes:
B4 30 CD 21 86 E0 3D 00 02 73 09 BA FC 01 B4 09 CD 21 CD 20 C6 06 E7 01 19 B4 0F CD 10 88 26 E8 01 BA 17 02 B4 09 CD 21 33 DB B4 45 CD 21 8B E8 B4 3E CD 21 BB 02 00 B4 45 CD 21 FC BA 1A 02 B9 00 10 8B DD B4 3F CD 21 0B C0 75 02 CD 20 8B C8 8B F2 AC
3C 1A 74 F5 3C 0D 75 07 C6 06 EA 01 01 EB 4C 3C 0A 75 06 FE 06 E9 01 EB 42 3C 08 75 0D 80 3E EA 01 01 74 37 FE 0E EA 01 EB 31 3C 09 75 12 8A 26 EA 01 80 C4 07 80 E4 F8 FE C4 88 26 EA 01 EB 1B 3C 07 74 17 FE 06 EA 01 8A 26 EA 01 3A 26 E8 01 76 09 FE
06 E9 01 C6 06 EA 01 01 8A D0 B4 02 CD 21 8A 26 E9 01 3A 26 E7 01 72 20 BA F0 01 B4 09 CD 21 B4 0C B0 01 CD 21 BA 17 02 B4 09 CD 21 C6 06 EA 01 01 C6 06 E9 01 01 4E 41 49 74 03 E9 6E FF E9 54 FF 18 50 01 01 00 00 00 00 00 0D 2D 2D 20 4D 6F 72 65 20
2D 2D 24 4D 4F 52 45 3A 20 49 6E 63 6F 72 72 65 63 74 20 44 4F 53 20 76 65 72 73 69 6F 6E 0D 0A 24 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 !
(Remember to terminate each line - except the last - with space!)
But that's not all. After a while, DH responded again Here's his advice on receiving files via RS-232 without comms software:
To receive a file sent by RS-232 using MORE.COM, on the Portfolio, execute “MORE <COM1 >FileName” (replacing “FileName” with the name under which to save the file). This will stream data from the COM port directly to the file (assuming no ^Z is encountered) WITHOUT locking up the keyboard! This allows you to advance the stream by repeatedly pressing Enter until the program automatically ends, signalling a complete transfer. It also means that you can still use CTRL+C if something goes wrong (something “COPY COM1 FileName” wouldn’t let you do, since it replaces all keyboard input with the COM port instead of simply opening it alongside). My Serial Interface hasn’t come through the post yet, so if someone with their own can test this for me, that would be great thanks!
The last (as for now) contribution by DH is a version of MORE.COM that can be typed in from command prompt without using B16CAT:
\176 ^N \254 \200 \162 4 ^B \162 \92 ^B , ^D \254 \192 \162 5 ^B \162 ] ^B \180 0 \205 ! \134 \224 H = \254 ^A w ^K \186 A ^B \180 ^R \208
\236 \205 ! \205 [SPACE] \198 ^F 0 ^B ^Y \180 ^O \205 ^P \134 \224 \162 1 ^B \144 \144 \144 \144 1 \219 \180 E \205 ! \137 \197 \180 = \254
\196 \205 ! \187 ^B \128 \129 \227 ^O ^A \180 E \205 ! \252 \186 _ ^B \185 ^A ^P I \137 \235 \180 ? \205 ! ! \192 u ^B \205 [SPACE] \137 \193
\137 \214 \172 0 \228 \254 \196 \168 \128 t ^D ^D \128 \235 Z ^L \128 = \154 ^A t \230 = \141 ^A u ^K \144 \144 \144 \198 ^F 3 ^B ^A \235 ]
\144 = \138 ^A u ^F \254 ^F 2 ^B \235 Q = \136 ^A u ^U \144 \138 ^V 3 ^B 0 \246 \254 \198 \129 ^Y0 ^A ^A t = \254 ^N 3 ^B \235 7 = \137 ^A u
^T \138 6 3 ^B \128 \198 ^F \254 \198 \128 \230 \248 \254 \198 \136 6 3 ^B \235 \30 = \135 ^A t ^Y \254 ^F 3 ^B \138 6 3 ^B : 6 1 ^B v ^K
\144 \144 \254 ^F 2 ^B \198 ^F 3 ^B ^A , \128 \136 \194 \180 ^B \205 ! \138 6 2 ^B : 6 0 ^B r $ \186 4 ^B \180 ^R \208 \236 \205 ! \180 ^L
\176 ^A \205 ! \186 \92 ^B \180 ^R \208 \236 \205 ! \198 ^F 3 ^B ^A \198 ^F 2 ^B ^A N A I \144 \144 t ^D \144 \233 A \255 \233 & \255 ^X P ^A
^A \141 \138 – - [SPACE] M o r e [SPACE] – - $ M O R E : [SPACE] I n c o r r e c t [SPACE] D O S [SPACE] V e r s i o n \141 \138 $
and hex codes for a little program that uses Portfolio-specific BIOS commands (int 61h):
B4 16 B9 19 00 B2 3C CD 61 B2 3B CD 61 B2 3C CD 61 B2 3B CD 61 B2 3C CD 61 B2 38 CD 61 B2 29 CD 61 B2 39 CD 61 B2 36 CD 61 CD 20 !
Now, Portfolio hackers, who's gonna pick up the gauntlet and write some more hex-code snippets?
This is DH once again:
This should work and would be some good code to incorporate into a countdown timer program:
B4 16 B9 14 00 B2 39 CD 61 D1 E1 B2 37 CD 61 D1 E9 B2 32 CD 61 D1 E1 B2 34 CD 61 D1 E9 B2 3D CD 61 B2 3B CD 61 B2 39 CD 61 B2 3B CD 61 CD 20 !
Here’s a program that dials a number you type in using the built in DTMF dialer. This program can be entered from the prompt as follows:
echo \161 y ^A % ^O ^O \163 y ^A 1 \192 \162 ~ ^A \176 \29 $ ^O \162 \127 ^A \180 ^F \254 \196 \254 \196 \254 \196 \186 X ^A \205 ! \186 y ^A \205 ! \180 ^F \128 \196 ^D \186 } ^A \205 ! \180 ^F \254 \196 \254 \196 \254 \196 \186 y ^A \205 ! \186 n ^A \205 ! \186 y ^A \205 ! \190 \127 ^A 0 \237 \138 ^N ~ ^A \180 ^W \205 a \205 [SPACE] \144 E n t e r [SPACE] n u m b e r [SPACE] t o [SPACE] d i a l : $ D i a l i n g . . . $ \29 * $ \144 2 ^A \29 $ >DIALER.COM
So you want to write programs. Ok, here are the first steps you should follow:
Sit down, take a deep breath and think, what kind of software you'd like to create. Should it be a game? a finance manager? a pack of useful scripts?
What is the destination platform? In other words, on which model will you run your program? Organiser II? Series 5mx? Or maybe you're about to make a cross-platform application?
Now that you've completed point 1 and 2, choose the best tool. OPL seems to be the best choice for most applications, at least for beginners. It will give you a wide variety of useful functions, covering graphics/animation, sound, GUI and integration with built-in software. On the other side, assembler will give you freedom, joy of hacking and great performance - of course if you're already familiar with assembly programming. However, it's pointless to write a home expense tracking suite with an extensive GUI in assembly language.
If you're planning a cross-psion application, running on the Series 7 as well as on Series 3, choose OPL. This will save you a lot of work you would spend porting your program to other platforms.
If your program will run only on EPOC machines, you may want to choose some more "mainstream" language, like Python, Perl, Java or Lua - especially if you have some previous experience. In this case, come back to the first part and read about the limitations. Having chosen one of the abovementioned, remember that you need to supply the users (if you're willing to publish your work) with the runtime libraries. It's really straightforward with Lua: there are separate .SIS packages available and all you need to do is to put them together with your application. Java needs JVM, the virtual machine available with the SDK (see part 1). Perl and Python require the interpreter to be installed.
Ok, you have chosen your tool? It's time to learn to use it. For OPL and SIBO/EPOC machines, read "Programming Psion Computers" - the Bible of Psion programming. Organiser programming tutorials may be found on the Organiser II homepage (see part 1).
If you have chosen assembler, you not only need to learn the mnemonics (assembly commands) for your platform, but also should become familiar with your computer's internals - read "Programming Psion computers" or the manuals on Org II homepage.
For those who want to write in OPL, especially for future game developers, there's an excellent programming tutorial in EPOC Entertainer, covering everything needed to write your own application - the tutorial takes you through the steps of game development. You can also look for some OPL tutorials for Symbian, e.g. this one.
Perl, Python, Lua and Java tutorials were mentioned in the first part.
Code, code, code. Practice makes perfect.
Portfolio's display is controlled by a Hitachi HD61830 chip. As I previously said, this makes it incompatible with the PC and more difficult to program. However, the only way to use dynamic graphics in your programs is to access the controller directly.
If you'd like to update the graphics in real time (e.g. in a game), the best idea would be to redraw the screen at once, so that you don't need to bother drawing each pixel separately. It is possible thanks to the routine by Milan and Martin Hrdlička:
refresh: cld push ax push cx push dx push si push di push ds mov si, 0 mov ax, 0b000h mov ds, ax mov di, 64 ref2: mov cx, 30 mov bx, si mov al, 0ah mov dx, 8011h cli out dx, al mov al, bl dec dx out dx, al sti mov al, 0bh inc dx cli out dx, al dec dx mov al, bh and al, 7 out dx, al sti ref1: lodsb ror al, 1 mov ah, al and ah, 136 ror al, 1 ror al, 1 mov bl, al and bl, 68 or ah, bl ror al, 1 ror al, 1 mov bl, al and bl, 34 or ah, bl ror al, 1 ror al, 1 and al, 17 or al, ah mov ah, al inc dx mov al, 0ch cli out dx, al mov al, ah dec dx out dx, al sti loop ref1 dec di jnz ref2 pop ds pop di pop si pop bx pop dx pop cx pop ax ret
Now, all you need to do is to update the graphics at B000:0000 each time before refreshing the screen. One pixel is one bit, so there are 64 lines by 240/8=30 bytes. That makes 1920 bytes and the actual position of a pixel in memory may be calculated using this formula:
byte = y * 30 + x / 8
bit = x mod 8
so, for example to draw the point at x=50, y=17 (0,0 is the top-left corner, 239,63 is the bottom-right) you need to set the bit number 2 at B000:0204 (that is 516 decimal). Obviously, clearing the bit clears the pixel.
More tips on programming graphics:
From Organiser to Series 5: Programming tools
It's not so far from the truth, that Psion Company has set the standards for many modern portable computers. Their sophisticated, sometimes revolutionary solutions pioneered the development of palmtops. Unfortunately, one of the great features of Psions not followed by today's palmtop market was the OPL. The idea of a built-in programming language wasn't new in those times - all home computers had BASIC interpreter on board - but OPL joined the ease of BASIC with the structural syntax and was well integrated with Psion's built-in facilities. And it was backwards compatible, as long as no system-specific functions were used. This means that you should be able to run your software written for the Organiser on a Symbian smartphone with just a few modifications! 
Apart from standalone programs, you can extend your system with OPL. The Calculator application on Series 3 Psions can perform calculations using built-in and user's own OPL functions. Also macros for Macro5 are written in OPL. On the Series 5 OPL programs can be extended by OPX modules written in C++. However, although OPL is the simplest way to write programs for Psions, it's not the only one.
On the opposite of OPL there are assemblers, allowing you to access directly machine's "guts". Since different models have different processors, it isn't possible to run your program designed for an Organiser on Series 3. Even Series 3 and 5 are incompatible.
Psion Organiser II models have an 8-bit HD6303 processor. You can program it using PCMAC. It's a cross-assembler, i.e. it's run on a PC and the generated machine code must be transferred to the Organiser.
All Series 3 models and the Siena have a 16-bit NEC V30 - which in fact is a low-consumption 8086 clone (although in different models it's clocked at different speeds). This means that you may use an x86 assembler, compile the code on a PC and it will be ready to run on the Psion. There are tons of commercial (TASM, MASM) as well as free- or shareware (A86, New Basic Assembler) assemblers. If you're willing to do the work on your Psion, there's even one that runs natively on your machine - S3A.
Series 5 models are powered by a 32-bit ARM710T. I know of two assemblers for them, both running on the Psion. The first is French Assembleur (unfortunately, the instruction manual is also in French) and the second is called simply ASM. I also read about "GB Assembler Studio" by Nicklas Larsson, but it seems to have disappeared from the Web.
Something else? Sure. Series 3 computers can be programmed in C. You'll find some good resources on Gareth and Jane Saunders' website. They have also some goodies for those who would like to write programs in C++ for their Series 5.
Of course that's not all. There are many more, especially for Psion Series 5. Among them are two Titans: Perl 5.6.1 and Python 2.2.1. (There's also Python 2.1 port, Epocpython). To me, the greatest drawback of these ports is the lack of Psion API (or I haven't found it). So they may be good for prototyping (in a limited manner, as Python 2.2 is an ancient version, eons before 2.7, not to mention 3k) or running some useful scripts (keep in mind, that they'll execute really slow), but nothing more. No real Psion applications written in Python/Perl. What a pity.
For those who want to program in a well-known, multi-platform and powerful language, there's Lua. Not only can you write standalone Lua programs, but also integrate Lua code into your OPL programs, making it possible to write applications utilizing Psion's features, such as GUI. Lua is available from FreEPOC.
You can also run Java programs on your Series 5 machine (Psion runs the Java Virtual Machine, programs need to be compiled on a PC). Among other, less known languages, is Prolog and even... a Brainfuck interpreter
- "Programming Psion Computers" by Leigh Edwards and other free e-books and manuals for both SIBO and EPOC programming
- Programming manuals for Psion Organiser II
- HD6303 and ARM assembly mnemonics are described in the abovementioned packages (Assembler for the Org II) or on their websites (ASM for Psion 5)
- Official home pages, where programming tutorials can be found: Python, Perl, Lua, Java
-  Actually, Organiser's OPL is not a good example, since it uses a slightly different syntax (e.g. no PROC-ENDP statements). But programs developed for the Series 3, even those with GUI, should work on Symbian. ↩
One of Atari Portfolio's weak points is the graphics. Not only has Portfolio very modest graphics capabilites (what can be understood), but also is hardly compatible with PCs. I think this is why there were so few games written for Pofo (Folidash and Phoenix are two of them).
There are two ways to display graphics on Portfolio: using interrupt 10h or sending data directly to the graphics controller. The former is very slow, so it's only intended to use when you want to introduce simple graphic elements (e.g. in board games), but its advantage is the compatibility - you'll be able to run your program on a PC. The latter is much faster - it's actually the only way to program animations - but your code will hang the PC.
Using int 10h is also much easier. If you want to draw an oblique line, you may type:
mov ax, 4 ; set graphics mode 4 int 10h mov cx, 0 ; initial X coordinate mov dx, 0 ; initial Y loop: mov ax,0c01h ; set pixel mov bh, 0 int 10h cmp cx, 63 je end inc cx inc dx jmp loop end: mov ah, 1 ; wait for a keypress int 21h mov ax, 7 ; set graphics mode 7 int 10h int 20h ; exit to DOS
Sounds familiar? Unfortunately, I won't tell you how to copy files using psychokinetic abilities. Instead I'll write about a brilliant idea by Viktor T. Toth, who found out how to write programs on Portfolio without any external compiler. If you're an assembler coder, you'll probably find it useful to write your own small applications. If not, I'll try to put some listings on my blog, including a serial transmission program (that is, the program that is not built-in, so you must copy it somehow to your Portfolio; if you don't have a parallel interface or a card, you're in deep ass).
The idea behind Viktor's solution was that you're - in limited fashion - able to machine-code from within DOS. The only obstacle is that not all ASCII codes may be entered using keypresses (e.g. 03 - Ctrl+C ). His workaround consists of two short programs that don't contain any "illegal" codes, so you can type them from DOS prompt. When you have successfully finished the second one, you'll be able to "compile" text files with hex-coded programs. Now you only need to write your program on a regular PC, compile it to a .com file, view that file with a hex editor and re-type the codes on your Portfolio.
The original step-by-step instructions are here, but I'll write a short tutorial, just in case 😉
First, you need to create CAT.COM. This tiny program allows you to enter any character (except Ctrl+C and Ctrl+S) and redirect it to a file. When in the DOS prompt, press Atari+LOCK to turn on NUM LOCK and type:
NOTE: \xxx means "hold Alt and type three digits from the numeric (red) keyboard". You should see a semigraphic character when you release Alt. ^x means Ctrl+X. ! is simply an exclamation mark (Shift+1).
If you made no mistakes, the file should be 17 bytes long and run without hanging the computer. And now, here comes the hard part. With CAT.COM you'll write the next program, H2C.COM, but this time the characters won't show up. Type:
Now, make sure that NUM LOCK is on (the cursor changes to underline) and then hit the following keys:
\180 ^H \205 ! < x t (
< : | ^B ^D ^I \177 ^D
\210 \224 $ \240 P \180 ^H \205
! < x t \233 < : |
^B ^D ^I $ ^O [ ^H \216
\136 \194 \180 ^B \205 ! \235 \208
\205 spc ^C
If you're lucky, you'll get a 50-byte-long file.
Now it's time to test the compiler. The example code on Viktor's page is long and complicated. Instead, open the built-in editor and type this:
b4 09 ba 0b 01 cd 21 b4 4c cd 21 x
without spaces and newlines! Save the file as HELLO.HEX and execute:
Yet you have to merge the text to your code. You may use either the text editor or CAT.COM, but remember to redirect CAT.COM's output to append the text to the end of HELLO.COM:
(the string must be terminated with $). Hit Ctrl+C (or save the file and hit Esc, when using editor).
If everything went right, typing HELLO should result in the good old hello message.
Read the comments to this post to find another solution to this problem by DH.