Rsin
Syntax
Variable = Rsin, { Timeout Label }
or
Rsin { Timeout Label }, Modifier..Variable {, Modifier.. Variable...}
Overview
Receive one or more bytes from a predetermined pin at a predetermined Baud rate in standard asynchronous format using 8 data bits, no parity and 1 stop bit (8N1). The pin is automatically made an input.
Parameters
Modifiers may be one of the serial data modifiers explained below. Variable can be any user defined variable. An optional Timeout Label may be included to allow the program to jump to a BASIC label if a byte is not received within a certain amount of time. It can also be one of the compiler directives; Break or Continue, if the command is used inside a loop. Break will exit a loop if a timeout occurs, and Continue will re-iterate the loop. Timeout is specified in units of 1 millisecond and is specified by using a Declare directive.
Example
Device = 18F25K20
Declare Xtal = 20 ' Tell the compiler the device will be operating at 20MHz
Declare Rsin_Timeout = 2000
' Timeout after 2 seconds
Dim MyByte as Byte
Dim MyWord as Word
MyByte = Rsin, {Label}
Rsin MyByte, MyWord
Rsin { Label }, MyByte, MyWord
Label: { do something when timed out }Declares
There are several Declares for use with Rsin. These are : -
Declare Rsin_Pin = Port.Pin Assigns the Port and Pin that will be used to input serial data by the Rsin command. This may be any valid port on the PICmicro™.
If the Declare is not used in the program, then the default Port and Pin is PORTB.1.
Declare Rsin_Mode = Inverted or True or 1, 0 Sets the serial mode for the data received by Rsin. This may be inverted or true. Alternatively, a value of 1 may be substituted to represent inverted, and 0 for true.
If the Declare is not used in the program, then the default mode is Inverted. Declare Serial_Baud = 0 to 65535 bps (Baud) Informs the Rsin and Rsout routines as to what Baud rate to receive and transmit data.
Virtually any Baud rate may be transmitted and received, but there are standard Bauds: -
300, 600, 1200, 2400, 4800, 9600, and 19200.
When using a 4MHz crystal, the highest Baud rate that is reliably achievable is 9600. However, an increase in the oscillator speed allows higher Baud rates to be achieved, including 38400 Baud.
If the Declare is not used in the program, then the default Baud is 9600.
Declare Rsin_Timeout = 0 to 65535 milliseconds (ms) Sets the time, in milliseconds, that Rsin will wait for a start bit to occur.
Rsin waits in a tight loop for the presence of a start bit. If no timeout value is used, then it will wait forever. The Rsin command has the option of jumping out of the loop if no start bit is detected within the time allocated by timeout.
If the Declare is not used in the program, then the default timeout value is 10000ms or 10 seconds.
Rsin Modifiers.
As we already know, Rsin will wait for and receive a single byte of data, and store it in a variable . If the PICmicro™ were connected to a PC running a terminal program and the user pressed the "A" key on the keyboard, after the Rsin command executed, the variable would contain 65, which is the ASCII code for the letter "A"
What would happen if the user pressed the "1" key? The result would be that the variable would contain the value 49 (the ASCII code for the character "1"). This is an important point to remember: every time you press a character on the keyboard, the computer receives the ASCII value of that character. It is up to the receiving side to interpret the values as necessary. In this case, perhaps we actually wanted the variable to end up with the value 1, rather than the ASCII code 49.
The Rsin command provides a modifier, called the decimal modifier, which will interpret this for us. Look at the following code: -
Dim bSerData as Byte
Rsin Dec bSerDataNotice the decimal modifier in the Rsin command that appears just to the left of the bSerData variable. This tells Rsin to convert incoming text representing decimal numbers into true decimal form and store the result in bSerData. If the user running the terminal software pressed the "1", "2" and then "3" keys followed by a space or other non-numeric text, the value 123 will be stored in the variable bSerData, allowing the rest of the program to perform any numeric operation on the variable. Without the decimal modifier, however, you would have been forced to receive each character ("1", "2" and "3") separately, and then would still have to do some manual conversion to arrive at the number 123 (one hundred twenty three) before you can do the desired calculations on it.
The decimal modifier is designed to seek out text that represents decimal numbers. The characters that represent decimal numbers are the characters "0" through "9". Once the Rsin command is asked to use the decimal modifier for a particular variable, it monitors the incoming serial data, looking for the first decimal character. Once it finds the first decimal character, it will continue looking for more (accumulating the entire multi-digit number) until is finds a nondecimal numeric character. Remember that it will not finish until it finds at least one decimal character followed by at least one non-decimal character.
To illustrate this further, examine the following examples (assuming we're using the same code example as above): -
Serial input: "ABC" Result: The program halts at the Rsin command, continuously waiting for decimal text.
Serial input: "123" (with no characters following it) Result: The program halts at the Rsin command. It recognises the characters "1", "2" and "3" as the number one hundred twenty three, but since no characters follow the "3", it waits continuously, since there's no way to tell whether 123 is the entire number or not.
Serial input: "123" (followed by a space character) Result: Similar to the above example, except once the space character is received, the program knows the entire number is 123, and stores this value in SerData. The Rsin command then ends, allowing the next line of code to run.
Serial input: "123A" Result: Same as the example above. The "A" character, just like the space character, is the first non-decimal text after the number 123, indicating to the program that it has received the entire number.
Serial input: "ABCD123EFGH" Result: Similar to examples 3 and 4 above. The characters "ABCD" are ignored (since they're not decimal text), the characters "123" are evaluated to be the number 123 and the following character, "E", indicates to the program that it has received the entire number.
The final result of the Dec modifier is limited to 16 bits (up to the value 65535). If a value larger than this is received by the decimal modifier, the end result will be incorrect because the result rolled-over the maximum 16-bit value. Therefore, Rsin modifiers may not (at this time) be used to load Dword (32-bit) variables.
The decimal modifier is only one of a family of conversion modifiers available with Rsin See below for a list of available conversion modifiers. All of the conversion modifiers work similar to the decimal modifier (as described above). The modifiers receive bytes of data, waiting for the first byte that falls within the range of characters they accept (e.g., "0" or "1" for binary, "0" to "9" for decimal, "0" to "9" and "A" to "F" for hex. Once they receive a numeric character, they keep accepting input until a non-numeric character arrives, or in the case of the fixed length modifiers, the maximum specified number of digits arrives. While very effective at filtering and converting input text, the modifiers aren't completely foolproof. As mentioned before, many conversion modifiers will keep accepting text until the first non-numeric text arrives, even if the resulting value exceeds the size of the variable. After Rsin, a Byte variable will contain the lowest 8 bits of the value entered and a Word (16-bits) would contain the lowest 16 bits. You can control this to some degree by using a modifier that specifies the number of digits, such as Dec2, which would accept values only in the range of 0 to 99.
Conversion Modifier Type of Number Numeric Characters Accepted
Dec{1..10} Decimal, optionally limited 0 through 9 to 1 - 10 digits Hex{1..8} Hexadecimal, optionally limited 0 through 9, to 1 - 8 digits A through F Bin{1..32} Binary, optionally limited 0, 1 to 1 - 32 digits
A variable preceded by Bin will receive the ASCII representation of its binary value. For example, if Bin Var1 is specified and "1000" is received, Var1 will be set to 8.
A variable preceded by Dec will receive the ASCII representation of its decimal value. For example, if Dec Var1 is specified and "123" is received, Var1 will be set to 123.
A variable preceded by Hex will receive the ASCII representation of its hexadecimal value. For example, if Hex Var1 is specified and "FE" is received, Var1 will be set to 254.
SKIP followed by a count will skip that many characters in the input stream. For example, SKIP 4 will skip 4 characters.
The Rsin command can be configured to wait for a specified sequence of characters before it retrieves any additional input. For example, suppose a device attached to the PICmicro™ is known to send many different sequences of data, but the only data you wish to observe happens to appear right after the unique characters, "XYZ". A modifier named Wait can be used for this purpose: -
Rsin Wait("XYZ"), SerDataThe above code waits for the characters "X", "Y" and "Z" to be received, in that order, then it receives the next data byte and places it into variable SerData.
Str modifier.
The Rsin command also has a modifier for handling a string of characters, named Str.
The Str modifier is used for receiving a string of characters into a Byte array variable.
A string is a set of characters that are arranged or accessed in a certain order. The characters "ABC" would be stored in a string with the "A" first, followed by the "B" then followed by the "C". A Byte array is a similar concept to a string; it contains data that is arranged in a certain order. Each of the elements in an array is the same size. The string "ABC" would be stored in a Byte array containing three bytes (elements). Below is an example that receives ten bytes and stores them in the 10 element byte array, bSerString: -
Dim bSerString[10] as Byte ' Create a 10 element byte array.
Rsin Str bSerString
' Fill the array with received data.
Print Str bSerString
' Display the string.If the amount of received characters is not enough to fill the entire array, then a formatter may be placed after the array's name, which will only receive characters until the specified length is reached. For example: -
Dim bSerString[10] as Byte ' Create a 10 element byte array.
Rsin Str bSerString\5
' Fill the first 5-bytes of the array
Print Str bSerString\5
' Display the 5-character string.The example above illustrates how to fill only the first n bytes of an array, and then how to display only the first n bytes of the array. n refers to the value placed after the backslash.
Because of its complexity, serial communication can be rather difficult to work with at times. Using the guidelines below when developing a project using the Rsin and Rsout commands may help to eliminate some obvious errors: -
Always build your project in steps.
Start with small, manageable pieces of code, (that deal with serial communication) and test them, one individually. Add more and more small pieces, testing them each time, as you go. Never write a large portion of code that works with serial communication without testing its smallest workable pieces first.
Pay attention to timing.
Be careful to calculate and overestimate the amount of time, operations should take within the PICmicro™ for a given oscillator frequency. Misunderstanding the timing constraints is the source of most problems with code that communicate serially. If the serial communication in your project is bi-directional, the above statement is even more critical.
Pay attention to wiring.
Take extra time to study and verify serial communication wiring diagrams. A mistake in wiring can cause strange problems in communication, or no communication at all. Make sure to connect the ground pins (Vss) between the devices that are communicating serially.
Verify port setting on the PC and in the Rsin / Rsout commands.
Unmatched settings on the sender and receiver side will cause garbled data transfers or no data transfers. This is never more critical than when a line transceiver is used(i.e. MAX232). Always remember that a line transceiver inverts the serial polarity. If the serial data received is unreadable, it is most likely caused by a Baud rate setting error, or a polarity error.
If receiving data from another device that is not a PICmicro™, try to use Baud rates of 9600 and below, or alternatively, use a higher frequency crystal.
Because of additional overheads in the PICmicro™, and the fact that the Rsin command offers no hardware receive buffer for serial communication, received data may sometimes be missed or garbled. If this occurs, try lowering the Baud rate, or increasing the crystal frequency. Using simple variables (not arrays) will also increase the chance that the PICmicro™ will receive the data properly.
Notes
Rsin is oscillator independent as long as the crystal frequency is declared at the top of the program. If no Xtal Declare is used, then Rsin defaults to a 4MHz crystal frequency for its bit timing.