jcs.org
Tools for working with Cidco Mailstations
1# Written by FyberOptic, archived from http://www.fybertech.net/mailstation/fyos_c_002.zip
2
3INTRO
4-----
5
6Loading code onto the Mailstation was once a lofty goal, but over time, some
7smart folk have figured out just how to do that. And the ironic part, as it
8turns out, is that the Mailstation itself includes the code which facilitates
9doing so.
10
11Mind you, we aren't going to reflash the Mailstation, we're merely going to
12take advantage of some of its features to run arbitrary code. This lets you
13keep the original firmware intact, without fear of bricking it, while still
14inserting a bit of permanent code onto it, which allows us to then easily
15transfer larger code via the parallel port into system memory. This not only
16makes it easy for debugging, but it saves wear and tear on the flash memory.
17
18I'm not aware of the details on all the Mailstation models, but most of the
19older ones should work with this process just fine. The only one that probably
20wouldn't is the 350. Possibly the 300 as well. I don't know anything about
21the latter, but I understand that the 350 uses an entirely different cpu.
22
23In any case, I'll go ahead and say the normal mumbo jumbo, where if you screw
24up and break your Mailstation, it's not my fault! This is all "try at your own
25risk" sort of stuff.
26
27
28LAPLINK
29-------
30
31Using a parallel laplink cable is required for the transfers. And
32forunately, this is the only extra hardware you require, short of a PC. If you
33don't have the cable, there's lots of resources for making it on the internet.
34In fact, here's you a pinout that I had handy:
35
36 1-1
37 2-15
38 3-13
39 4-12
40 5-10
41 6-11
42 8-NC
43 9-NC
44 10-5
45 11-6
46 12-4
47 13-3
48 14-14
49 15-2
50 16-16
51 17-17
52 18-NC
53 19-NC
54 20-NC
55 21-NC
56 22-NC
57 24-NC
58 24-NC
59 25-25
60
61There's question over whether 1, 15, 16, and 17 are necessary, but it couldn't
62hurt to do them anyway in case something else wants them in the future that you
63try to use the cable on.
64
65
66HEX VIEWER
67----------
68
69Once you have a cable handy, the next question is "So how do I copy code from
70my computer to the Mailstation?" Well we're not quite there yet. We still
71have to put code onto the Mailstation to allow it to be able to copy your
72own code over. We start by taking advantage of one of the Mailstation's
73hidden features: the hex editor.
74
75Accessing the hex editor seems to vary from model to model. The first step
76is reaching the diagnostic screen. On my original black DET1 running v3.03a
77firmware, the key combination is Function + Shift + T when powering the device
78on. I got this information from the spew.txt on the Yahoo Mailstation group
79(http://tech.groups.yahoo.com/group/mailstation/), written by Cyrano Jones
80(who discovered much of what I will discuss here). You can find it in the
81Files/Mailbug section. Quoted from his file:
82
83"Enter test mode with vulcan nerve pinch while booting. <func><shift><t>, or
84<func><size><t> or on the newer models, <func><q><a>, then "qa781206", without
85the quotes, of course."
86
87Hopefully one of those will work for you. Once you're into the diagnostic
88screen, press Shift + F5 to get into the hex editor. The F keys are those gray
89rectangular ones beneath the screen.
90
91Keep in mind that this does not allow you to modify the codeflash on the
92device. It's merely for the 512KB of dataflash, which is where the Mailstation
93stores all your email and settings and such. Something else the Mailstation
94stores here however are third-party applications, particularly ones that were
95included from Yahoo, for getting weather and TV listings or whatever. These
96weren't included with all Mailstations, but the functionality to use them
97apparently was. This is what we're going to take advantage of to run code on
98the device, since aforementioned smart folk figured out the structure to these
99apps, allowing us to create our own.
100
101We're not ready to do so yet, but at any time, you can hit the Back button to
102exit the hex editor, and then press Q at the diagnostic menu to restart the
103Mailstation. It prompts you at this point whether you want to clear the
104dataflash (much like when you remove power while the device is on), but just
105skip past that unless you really want to clear everything for some reason.
106
107
108APP RECORDS
109-----------
110
111First of all, we need to find out how many apps are already installed on your
112device, to know which area to place our own. So while in the hex editor, press
113G to bring up the Goto prompt, and type in "020000", followed by pressing
114Enter. This takes you to the location which stores info about how many
115apps are installed/where their code is stored/etc. You may see nothing
116but zeroes along the top row, but this just means you have no apps (much like
117mine did). Then again, you might have some stuff listed, which means you
118probably do have a couple. Here's the known structure of the data starting at
1190x020000:
120
121nn ?? ?? ?? <-- number of apps
122xx 00 xx xx xx 18 <-- data for 1st app
123xx 01 xx xx xx 19 <-- data for 2nd app
124xx 02 xx xx xx 1a <-- data for 3rd app
125xx 03 xx xx xx 1b <-- data for 4th app
126xx 04 xx xx xx 1c <-- data for 5th app
127
128The first four bytes are header info, with only the first byte being known. It
129holds the number of apps you have. Immediately following that, you have
130records of six bytes each for each app. It's believed that you can have five
131apps at most. Most of these bytes are also unknown, but the second in each is
132the dataflash page number it resides on (out of 32 pages, 16KB each = 512KB),
133and the sixth byte is the app number. The values for each app must be left as-
134is unless you know what you're doing. You'll mostly only be changing the
135number of apps.
136
137
138HEX VIEWER TO HEX EDITOR
139------------------------
140
141Changing anything requires using the hex editor to actually edit, which,
142believe it or not, it can't do by default! It's actually more of just a hex
143viewer upon startup. But luckily they included a back door of sorts, which
144turns it into a true hex editor.
145
146To get into actual hex editor mode, press G for the Goto command, then type in
147this address: "710304x", minus quotes of course. And don't forget the x at the
148end, even though you won't see it being typed. Once you put this in, you don't
149have to press enter. If you do, you'll lose your place. Hit the Back button
150on the keyboard instead to return the editor, and you should still be at the
1510x020000 location. And now you'll be in actual hex editor mode.
152
153To edit the current screen of data, you hit the "s" key on your keyboard. The
154original instructions say control-s, or function-s, but just "s" worked for me.
155You can use the arrow keys to move around in the data, and type in new values
156in hex. Pressing the "s" key again will save the current changes back to the
157dataflash. You must do this before leaving the current screen of data, or
158you'll lose any changes. Hitting the Back button will also result in losing
159changes.
160
161
162So now I'll break the instructions up:
163
164- Method A will be if you have Yahoo apps installed but wish to just overwrite
165one of them.
166
167- Method B will be if you have Yahoo apps but want to add a new one.
168
169- Method C will be if you have no apps at all and want to add one.
170
171
172METHOD A
173--------
174So you already have some apps installed, but don't care about those, and just
175want to take the easy route and overwrite one of them. That's probably the
176easiest method. It means you don't have to edit anything here at 0x020000, as
177long as you see data to at least indiciate one or more apps. I expect you
178wouldn't have chosen method A if not. But if this is your method, we'll
179replace the first app, so for future reference, you need to remember that
180you'll be using dataflash page 0 to put your actual app in. All you need to do
181now is go to the LOADER APP section.
182
183If you plan to add more apps in the future though, I suggest reading METHOD B
184as well.
185
186
187METHOD B
188--------
189This section will be slightly tricky, but mostly just because it might mean
190some counting. You probably already have two apps installed (which is what
191will be assumed for most of this section), and while you might think it's a
192simple matter of changing that "2" to a "3" at the beginning of the apps
193header, it's not quite. If you did think that though, you were partially
194right, because you certainly will need to increment that first value at
1950x020000. Go ahead and do so. Use the instructions from earlier to make sure
196you're in actual hex editor mode if necessary, then just type over that value
197with your new one. If you had two apps, it should now show that you have
198three.
199
200In fact, at this point, if you saved the data (pressing "s") and went back and
201looked in the Extras section on the Mailstation, you'd likely see a third extra
202app over on the second page of apps, just minus an icon or name. It would be
203selectable though, which would indiciate what you've done so far worked. If
204you do go check this out though, make sure you follow all the previous
205instructions again to make it back to this point in the hex editor at 0x020000.
206
207Now is the counting part I mentioned. The problem with preinstalled apps is
208that there's only an app record for just the apps installed. That means we
209need to add a new one at the end of that, so that it'll know what page of
210dataflash the code is in and such when you run the third app. If you run the
211third app without this data specified, it'll almost always run the first Yahoo
212app (or whatever app you have in that location).
213
214So we're going to assume you have two apps already installed, and are wanting
215to add a third. This means counting over past the six-byte app records for the
216two apps already installed in order to add the bytes for the third. Remember
217that the app info area is formatted like this:
218
219[4 bytes header][6 bytes of app record 1][6 bytes of app record 2]
220
221The very first byte in the first four of course being the number of apps
222installed, which you should have already changed. We need to add another six
223bytes at the end of all of this. If you only had one app installed, you'd have
224to count over until past the last byte of the first app record, but luckily,
225having two apps installed means 16 bytes total (4 + 6 + 6). The hex editor
226shows 16 bytes per line. This means that instead of counting, you can simply
227go to the second line on the screen, aka address 0x020010. If you only had one
228app already, you'd have to count over to 0x02000A.
229
230Now, what you put at this location is dependant on the app number you're about
231to install. From earlier, this is the known structure of the app records:
232
233xx 00 xx xx xx 18 <-- data for 1st app
234xx 01 xx xx xx 19 <-- data for 2nd app
235xx 02 xx xx xx 1a <-- data for 3rd app
236xx 03 xx xx xx 1b <-- data for 4th app
237xx 04 xx xx xx 1c <-- data for 5th app
238
239If you have two apps installed already, then it's the data for the third app
240you need to put in. Since we don't know what the "xx" values are for, use
241"00". It works fine for me. So, for example, if you're adding in app three,
242you'd go to the second line on the screen when at 0x020000(aka address
2430x020010 now), and put in the following bytes: "00 02 00 00 00 1a". These
244bytes tell it to go to dataflash page 2 to run the app, and that the internal
245app number is 1a. The latter isn't important to us (but is important to
246include).
247
248What is important though is that you remember the dataflash page number from
249the line you add. This is because you have to know which page your app will
250run in, in order to know which page to put the code, later in the LOADER APP
251section. If you put it in the wrong page, it naturally won't run.
252
253While you're here, you might want to go ahead and add in the remaining bytes
254necessary to identify the rest of the five total apps. This will be useful if
255you want to add in more apps in the future, and would later require you to only
256change the first byte in this area, aka the number of apps, when adding
257another. So for example, if you just added in app three using the previous
258instructions, then all you need to do is type in the data for apps four and
259five right afterward.
260
261Don't forget to press "s" again to save your changes! Now, with your proper
262dataflash page number in mind, go on to the LOADER APP section.
263
264
265METHOD C
266--------
267This method is probably the second easiest aside from A, because it just means
268typing in bytes. You're probably here if you have no apps installed, or if you
269just don't care enough about the Yahoo apps to worry about them being there at
270all.
271
272So, make sure you're in actual hex editor mode, and that you're at location
2730x020000. We're going to add in the app header, and all five app records.
274This means that if you decide to add more apps in the future, all you have
275to do is increment the first byte, since all the proper app records will
276already be in place.
277
278So, at 0x20000, we want to put in the following bytes:
279
28001 00 00 00 00 00 00 00 00 18 00 00 00 00 00 18
28100 01 00 00 00 19 00 02 00 00 00 1a 00 03 00 00
28200 1b 00 04 00 00 00 1c
283
284The first byte obviously indicates we should now have one app. Make sure to
285hit "s" to save all this! It couldn't hurt to verify you typed in the proper
286bytes, as well. If you want to see if it worked, exit out of the hex editor,
287and go to the Extras area on your Mailstation. On the right, you should now
288have a new app, with no icon or label, but it should be selectable. Running it
289at the moment will probably crash your Mailstation though.
290
291Since this will be your first app, you'll be installing the code into dataflash
292page 0. Remember this value, then head on to the next section, LOADER APP.
293
294
295LOADER APP
296----------
297
298Okay, if you used methods B or C, you should have modified the apps header to
299specify the new number of apps, and added any necessary app records to be able
300to have your own apps.
301
302And no matter what method you used, you should know your dataflash page number to
303put the actual app at.
304
305This is where we're going to put the actual code! It also holds icon and icon
306label data, but we're not going to put an icon, just for the sake of typing
307less bytes in. Yes, you have to type in every byte of code for this manually,
308like in the old days. This is why the code is going to be as brief and to the
309point as possible. Its sole purpose will be loading code from your PC to the
310Mailstation, and running it. In fact, it won't even display anything on the
311screen while it's doing it! But we'll know it if it's loading, because the
312host loader app on the PC side will show us.
313
314In any case, let's put in some code. The first step is determining the
315location in the hex editor to go in order to do it. See, when you launch the
316app via the Mailstation, it looks in the app record and determines the
317dataflash page to load into slot4000 (16KB from 0x4000-0x7FFF in the
318Mailstation address space). As mentioned earlier, the dataflash is 512KB,
319resulting in 32 "pages" of flash that can be put into slot4000 (or slot8000 for
320that matter). Some of the later pages though are used for storing email and
321all that, so we wouldn't want to mess with those. You've already told
322it what page numbers each app uses anyway when you put in the app records
323earlier, and the Mailstation knows not to store anything important in those
324pages apparently.
325
326So this just takes a little math to determine the actual starting address in
327the dataflash that you need to put your code in. You basically just multiply
328your page number by 0x4000. So page 0 would be address 0x0000, page 1 would be
3290x4000, page 2 would be 0x8000, etc.
330
331I'll make it easy for you actually. If you're using method A or C, your
332address will be 0x0000. If you're using Method B, it's PROBABLY going to be
3330x8000, if you already had two apps installed. If you had some odd amount of
334apps installed, calculate accordingly.
335
336Now that you know your starting address in the dataflash, that's where we need
337to go. Using the Goto command in the hex editor, just punch in your address.
338Make sure you add enough zeroes into the blank, since it holds six characters.
3390x4000 would be "004000", for example.
340
341Now you're at the starting address of where your app should be! It's probably
342a bunch of zeroes. If you're overwriting a pre-existing Yahoo app, then it's
343probably a bunch of gibberish. Either way, we're overwriting it at this point.
344Make sure you put in the backdoor code mentioned earlier, hit "s" to enter edit
345mode, and type in these bytes:
346
347C3 2D 40 1A 40 0E 40 09 40 00 00 00 00 00 01 00
34806 00 06 00 4C 6F 61 64 65 72 C5 E5 AF D3 08 3C
349D3 07 CD 27 80 B7 CA 22 40 7D E1 C1 C9 CD 1A 40
3506F CD 1A 40 67 01 00 80 CD 1A 40 57 3E 01 D3 08
351D3 07 7A 02 03 2B AF B4 C2 38 40 AF B5 C2 38 40
352C3 00 80
353
354This is the code from loaderapp.bin, if you're curious. If you want to see the
355source to have some idea what it's doing, look at loaderapp.asm.
356
357You might want to visually verify your bytes, because it's extremely easy to
358make a mistake. One wrong letter or number could mess up the entire program.
359
360That's it! If you haven't already, hit "s" to save. Now you can go back out
361of the hex editor and into the Mailstation, look in the Extras area, and you
362should see the "Loader" app. If this is your first app, it'll be on the first
363page. If you already had some apps, it'll be on the second page.
364
365Keep in mind that running this won't do anything until you actually try to send
366code to it. It'll actually seem like it's frozen up (since it's constantly
367waiting for a byte from the parallel port). And if something ever goes wrong
368during a transfer (which can happen occasionally), you'll have to reset the
369Mailstation either with the reset button on back, or cycling the power.
370
371Now to send your own code to it!
372
373
374MAILSEND
375--------
376Mailsend is the other side of the transfer process that I wrote, which you run
377on your PC. It's a command-line Windows app.
378
379That said, open up a command prompt window, and navigate to where you put all
380the files. Sometimes it's easiest to just put it all in c:\mailstation, which
381is what I do.
382
383Mailsend assumes your PC's parallel port runs on the fairly standard port
3840x378. If not, you're going to have some problems. I have no idea if this is
385compatible with those USB->Parallel dongles out there, either. But almost
386every computer still made has a parallel port built into it, which should work
387with this just fine.
388
389To try it out, run "mailsend fyos_bin.bin" on the PC. It'll prompt you to
390press enter to continue. At this point, you need to run Loader on the
391Mailstation. Doing so won't give you any sort of visual indication, but you'll
392know it's working here in a second. Once Loader is running, hit return on the
393PC. You should start to see a byte counter as it transfers data to the
394Mailstation. When it's done, it'll return to the command prompt, and your
395Mailstation should be running whatever you just send to it. In this case,
396FyOS. If so, then congratulations, you can now transfer any binary file to the
397Mailstation!
398
399
400THE END?
401--------
402
403It's important to remember that your code is loaded into slot8000 (16KB from
4040x8000 to 0xBFFF), in ram page 1. 0xC000 to 0xFFFF is ram page 0, which is
405fixed and can't be swapped (as far as we know). The Mailstation uses page
4060 to store variables and such for its own code. This means you should keep
407the binaries you send less than 16KB, or you'll overwrite that stuff. If
408that's your intention, then fine, but keep in mind that interrupts are not
409disabled in the Loader app, meaning parts of the code you send that span
410past 0xC000 could get overwritten before it even gets a chance to execute. You
411could modify Loader to disable them however (then reassemble it, and type in
412the bytes again of course), but you should know what you're doing in such a
413case. No interrupts means no keyboard support via the firmware routines, for
414example.
415
416That's about it for this tutorial. If you have any questions/comments, feel
417free to let me know at fyberoptic@gmail.com. As mentioned in the readme, I
418also frequent the Yahoo group, where others might be able to help you as well:
419
420http://tech.groups.yahoo.com/group/mailstation/
421
422Have fun!
423
424
425 - FyberOptic
426
427
428