-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy path10-04-accessing-a-serial-port.html
373 lines (294 loc) · 17.1 KB
/
10-04-accessing-a-serial-port.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
<!doctype html>
<html lang="en">
<head>
<!--
This Amos Professional Manual is written by asymetrix for the Amiga community and should stay completely FREE FOREVER.
Created 2008. :)
It was created from the original AMOS Professional Manual by Europress Software Ltd.
It has been updated by Fredrik Rambris.
-->
<title>Accessing a Serial Port - AMOS Professional Manual</title>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, user-scalable=yes, initial-scale=1.0">
<meta http-equiv="X-UA-Compatible" content="ie=edge">
<meta name="keywords" content="Amos Professional, Amiga, Programming, Basic, Francois Lionet, Europress Software Ltd, Amos, computing, code, AmigaDOS">
<meta name="author" content="asymetrix,Fredrik Rambris">
<link rel="GitHub" href="https://github.com/fredrik-rambris/amospromanual">
<meta property="og:site_name" content="AMOS Professional Manual">
<meta property="og:image" content="https://amospromanual.dev/images/cover.jpg">
<link rel="stylesheet" type="text/css" href="styles.css">
<link rel="canonical" href="https://amospromanual.dev/10-04-accessing-a-serial-port.html">
</head>
<body>
<section>
<h1>Accessing a Serial Port</h1>
<p>
Here is the Chapter which explains how AMOS Professional is used as the gateway to the world
of computerised communications.</p>
<p>
The I/O Extension provides you with all the commands needed to exploit the Amiga's serial port
for the following purposes:</p>
<ul>
<li>Long-distance multi-user games played between any number of Amiga users.</li>
<li>Network communications between desks, offices, classrooms and continents!</li>
<li>MIDI interfacing for musicians, between the Amiga and synthesizers, drum machines and
sequencers.
</li>
</ul>
</section>
<section id="01-opening-the-serial-port">
<h2>Opening the Serial Port</h2>
<p>
A serial device refers to any machine that can communicate with the Amiga via its Serial Port.
These devices include modems, MIDI systems and of course, other Amigas.</p>
<h3 class="command" id="i-serial-open">SERIAL OPEN</h3>
<p><i>instruction: open a channel for Serial Input/Output</i><br>
<b>Serial Open</b> Channel number,Port number<br>
<b>Serial Open</b> Channel number, Port number,Shared,Xmode,7wires</p>
<p>
The SERIAL OPEN command is used to open a communication channel between the Amiga and
a serial device. The following parameters can be given with this instruction:</p>
<p>
The Channel number is an identification number that will be used for <b>all</b> subsequent
communication commands. The values for this number range from zero to 3.</p>
<p>
The Port number is normally set to zero, and it specifies the logical device number of the Serial
Port. For Amigas equipped with a Multi-Serial card that offers additional Serial Ports, these extra
ports can be accessed by specifying a Port number from 1 upwards.</p>
<p>There are three optional parameters that can also be given, as follows:</p>
<p>
The Shared parameter refers to a value which acts as a flag, telling AMOS Professional that the
serial device can be shared with other tasks that are currently running on the computer. In other
words, this parameter is used for multi-tasking. A value of zero (False) will grab the specified
channel for AMOS Professional programs, and will deny access to any other programs. A value
of -1 (True) will allow the Serial Port to be shared between several programs in memory. You are
warned to use this system with great care, to avoid crashing your Amiga.</p>
<p>
The Xmode is a val.-Lie which is used to toggle the checking system known as XON/XOFF. This
system makes checks during the transmission of data over a serial line. It is essential to set this
flag when the device is first opened, even if the device will not be required until later. The
default value is zero (False), and this means that the system is normally disabled. To enable the
checking system, a value of -1 (True) must be set. Once the port has been opened, the XON and
XOFF characters must be set using a SERIAL X command, which is explained later.</p>
<p>
The last of the three optional parameters concerns the "7 wires system" of communication.
The default value for this parameter is set to zero (False), and a value of -1 (True)
tells the device to use this system.</p>
<p>
When the SERIAL OPEN command is called for the first time, the Serial Device library is loaded
from the System disc automatically, so make sure that this disc is available in the current drive.</p>
<h3 class="command" id="i-serial-close">SERIAL CLOSE</h3>
<p><i>instruction: close one or more Serial channels</i><br>
<b>Serial Close</b><br>
<b>Serial Close</b> Channel number</p>
<p>
The use of this instruction closes all currently opened serial channels with no check for any
errors. If an optional channel number is given, the specified channel will be closed using all
normal error checks.</p>
<p>
Whenever a program is run from AMOS Professional, any opened channels will be closed
automatically.</p>
</section>
<section id="02-setting-the-serial-parameters">
<h2>Setting the serial parameters</h2>
<p>
The default settings for Serial Channels correspond to the standard Minitel protocol used in
France, as follows:</p>
<pre>
1200 Baud
7 bits
1 stop bit
Even parity.
</pre>
<p>These settings can be changed using the instructions that are explained next.</p>
<h3 class="command" id="i-serial-speed">SERIAL SPEED</h3>
<p><i>instruction: set transfer rate for a serial channel</i><br>
<b>Serial Speed</b> Channel number,Baud rate</p>
<p>
This sets the current data transfer rate (the Baud rate) of the given channel, for both the sending
and receiving operations. A Baud rate cannot be split for a. single channel. If the specified
transfer rate is not supported by the current serial device, it may be rejected by the system.</p>
<h3 class="command" id="i-serial-bits">SERIAL BITS</h3>
<p><i>instruction: set the number of bits for transmission of characters</i><br>
<b>Serial Bits</b> Channel number,number of bits,number of Stop bits</p>
<p>
This command is used to assign the number of bits that are to be used for each character that is
transmitted. After the channel number is specified, give the number of bits followed by the
number of Stop bits to be used.</p>
<h3 class="command" id="i-serial-parity">SERIAL PARITY</h3>
<p><i>instruction: set parity checking for a serial channel</i><br>
<b>Serial Parity</b> Channel number, Parity</p>
<p>
The SERIAL PARITY instruction sets the parity checking to be used for the specified
serial channel.</p>
<p>Here is a list of the available settings for the Parity parameter:</p>
<table>
<tbody>
<tr><td>-1 </td><td>No parity</td></tr>
<tr><td>0 </td><td>Even parity</td></tr>
<tr><td>1 </td><td>Odd parity</td></tr>
<tr><td>2 </td><td>Space parity</td></tr>
<tr><td>3 </td><td>Mark parity</td></tr>
</tbody>
</table>
<p>This Parity bit may be set using the BSET or BCLR instructions, as follows:</p>
<code class="prefix ex">P=0 : Bset 0,P: <comment>Rem Odd parity</comment>
Bclr 1,P : <comment>Rem Normal parity</comment>
Serial Parity 1,P : <comment>Rem Set parity using the value in P</comment>
</code>
<h3 class="command" id="i-serial-x">SERIAL X</h3>
<p><i>instruction: set handshaking system of serial channel</i><br>
<b>Serial X</b> Channel number,Xmode</p>
<p>
This command is used to enable or disable the XON/XOFF handshaking system, which checks
data transmission. A value of -1 (True) will disable the system, whereas any other value will turn
it on. The Xmode parameter should be loaded with the correct control characters, which must be
specified in the following format:</p>
<code class="prefix ex">Xmode=XON110000000+XOFF*$1000</code>
</section>
<section id="03-sending-and-receiving-serial-information">
<h2>Sending and receiving Serial information</h2>
<h3 class="command" id="i-serial-send">SERIAL SEND</h3>
<p><i>instruction: output a string via a serial channel</i><br>
<b>Serial Send</b> Channel number,string</p>
<p>
This is used to send the given string directly to the selected serial channel, without waiting
for the data to be transmitted through the actual port. This means that the SERIAL CHECK
function must be used to detect when the transmission of data has been completed, and this is
explained below.</p>
<h3 class="command" id="i-serial-out">SERIAL OUT</h3>
<p><i>instruction: output a block of raw data via a serial channel</i><br>
<b>Serial Out</b> Channel number,address,length</p>
<p>
This command is identical to SERIAL SEND, except for the fact that it works with raw data,
instead of a string. Specify the channel number as usual, followed by the address in memory of
the data to be transmitted, and the length of the data given in the number of bytes to be sent.</p>
<h3 class="command" id="fn-serial-get">SERIAL GET</h3>
<p><i>function: get a byte from a serial device</i><br>
value=<b>Serial Get</b>(Channel number)</p>
<p>
To read a single byte from a serial device, use the SERIAL GET function and
specify which channel is to be examined. If no data is available,
a value of -1 will be returned.</p>
<h3 class="command" id="fn-serial-input-dollar">SERIAL INPUT$</h3>
<p><i>function: get a string from the Serial Port</i><br>
string=<b>Serial Input$</b>(Channel number)</p>
<p>
This function is used to read an entire string of characters from the Serial Port. If no data is
available an empty string will be returned, otherwise the string will contain all the bytes that
have been transmitted via the serial line up to the present moment.</p>
<p>
Care should be taken when using this function with high speed transfers, such as those from
MIDI devices. If the waiting time between each receive is too long, the system may overload and
generate errors such as "string too long" or "serial device buffer overrun".</p>
<p>
Transmitting a very large string can take a long time, especially at low Baud rates. With AMOS
Professional multi-tasking, a program will only continue after a SERIAL SEND instruction. To
avoid corrupting data, the following system should be employed:</p>
<ul>
<li>Use the SERIAL CHECK function before using lengthy strings.</li>
<li>Perform a "garbage collection" using X =FREE, to ensure that the program will not provoke
such an operation spontaneously.
</li>
<li>Use the SERIAL OUT command and set the address parameter to contain the location of a
memory bank that has been previously reserved.
</li>
</ul>
</section>
<section id="04-other-serial-commands">
<h2>Other Serial commands</h2>
<h3 class="command" id="i-serial-buf">SERIAL BUF</h3>
<p><i>instruction: set the size of the serial buffer</i><br>
<b>Serial Buffer</b> Channel number,length</p>
<p>
This allocates the length of the buffer space for the required channel, specified in the number of
bytes to be allocated. The minimum allocation is 64 bytes, and the default setting is 512 bytes.
You are recommended to increase the buffersize for high speed transfers of data.</p>
<h3 class="command" id="i-serial-fast">SERIAL FAST</h3>
<p><i>instruction: engage fast mode for data transfer</i><br>
<b>Serial Fast</b> Channel number</p>
<p>
Use this command to set a special "fast" flag in the current serial device, which disables much of
the internal checking process that can slow down the communication process. This is
recommended for high speed transfers. Please note that when SERIAL FAST is called, the
protocol is changed to: even parity, no XON/XOFF and 8 bits.</p>
<h3 class="command" id="i-serial-slow">SERIAL SLOW</h3>
<p><i>instruction: re-set slow mode for data transfer</i><br>
<b>Serial Slow</b> Channel number</p>
<p>
This instruction slows the serial device transmission back to normal speed, and all of the internal
error checks are enabled once more.</p>
<h3 class="command" id="fn-serial-check">SERIAL CHECK</h3>
<p><i>function: report current serial device activity</i><br>
status=<b>Serial Check</b>(Channel number)</p>
<p>
This function obtains a report on the status of the current serial device. It can be used to check
whether all of the information to be transmitted by a previous SERIAL SEND command has
been sent. If a value of zero (False) is returned, the last Serial command is still being executed. If
the value is -1 (True) the transmission has been completed.</p>
<h3 class="command" id="fn-serial-status">SERIAL STATUS</h3>
<p><i>function: report status of the serial port</i><br>
bit-map=<b>Serial Status</b>(channel number)</p>
<p>
The SERIAL STATUS function provides detailed information concerning the current status of
the serial port. The channel number parameter refers to an open channel that has been
previously assigned to the serial port with a SERIAL OPEN command. The report is returned in
the form of a bit-map holding the status of fifteen different parameters. Here is a table of the
various possibilities. If the relevant bit is set to the value under the "Active" column, the
associated status has been successfully detected. Any other value indicates that the option is
currently idle.</p>
<table>
<thead>
<tr><th>Bit</th><th>Active</th><th>Status</th></tr>
</thead>
<tbody>
<tr><td>0</td><td>-</td><td>Reserved</td></tr>
<tr><td>1</td><td>-</td><td>reserved</td></tr>
<tr><td>2</td><td>1</td><td>Parallel "select" for A1000 machines. For the A500 and A2000, "select" is also connected to the serial port "Ring Indicator".</td></tr>
<tr><td>3</td><td>0</td><td>DSR (Data Set Ready)</td></tr>
<tr><td>4</td><td>0</td><td>CTS (Clear To Send)</td></tr>
<tr><td>5</td><td>0</td><td>Carrier Detect</td></tr>
<tr><td>6</td><td>0</td><td>RTS (Ready To Send)</td></tr>
<tr><td>7</td><td>0</td><td>DTR (Data terminal Ready)</td></tr>
<tr><td>8</td><td>1</td><td>Hardware overru</td></tr>
<tr><td>9</td><td>1</td><td>Break sent (most recent output)</td></tr>
<tr><td>10</td><td>1</td><td>Break received (as latest input)</td></tr>
<tr><td>11</td><td>1</td><td>Transmit x-OFF</td></tr>
<tr><td>12</td><td>1</td><td>Receive x-Off</td></tr>
<tr><td>13</td><td>-</td><td>Reserved</td></tr>
<tr><td>14</td><td>-</td><td>Reserved</td></tr>
<tr><td>15</td><td>-</td><td>Reserved</td></tr>
</tbody>
</table>
<h3 class="command" id="fn-serial-error">SERIAL ERROR</h3>
<p><i>function: report success of the last data transfer</i><br>
status=<b>Serial Error</b>(Channel number)</p>
<p>
The SERIAL ERROR function is used to look for the Error byte in the serial device.
A value of zero (False) confirms that all is well, whereas 4 (True) indicates
that there was an error in the last transmission.</p>
<h3 class="command" id="i-serial-abort">SERIAL ABORT</h3>
<p><i>instruction: stop current data transfer</i><br>
<b>Serial Abort</b>(channel number)</p>
<p>
This command halts any serial operations that have been commenced by a SERIAL SEND or
SERIAL OUT command, and leaves the channel clear. It allows an instant quit from a transfer,
without the need to wait for current activities to be completed.</p>
<h3 class="command" id="fn-serial-base">SERIAL BASE</h3>
<p><i>function: get the address of the serial base</i><br>
address=<b>Serial Base</b></p>
<p>
The SERIAL BASE function is especially useful for systems programmers. It returns the base
address of the i/o structure of the current serial channel, allowing system functions to be called
directly from an AMOS Professional program with EXEC. You are warned not to use this
function unless you know precisely what you are doing, otherwise any mistakes can crash your
computer.</p>
</section>
<footer>
<a href="10-03-accessing-a-printer.html" rel="prev">Accessing a Printer</a>
<a href="./">Contents</a>
<a href="14-appendix-g-command-index.html">Index</a>
<a href="10-05-the-parallel-port.html" rel="next">The Parallel Port</a>
</footer>
</body>
</html>