This repository has been archived on 2024-09-22. You can view files and clone it, but cannot push or open issues or pull requests.
pbi-ide/help/BasicStampHelp/Content/LanguageTopics/Reference/Adapt.htm

272 lines
23 KiB
HTML
Raw Normal View History

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns:MadCap="http://www.madcapsoftware.com/Schemas/MadCap.xsd" MadCap:lastBlockDepth="6" MadCap:lastHeight="94" MadCap:lastWidth="853" MadCap:disableMasterStylesheet="true" MadCap:tocPath="PBASIC Language Reference" MadCap:InPreviewMode="false" MadCap:PreloadImages="false" MadCap:RuntimeFileType="Topic" MadCap:TargetType="WebHelp" lang="en-us" xml:lang="en-us" MadCap:PathToHelpSystem="../../../" MadCap:HelpSystemFileName="Default.xml" MadCap:SearchType="Stem">
<head><title>Adapt BS2 Code to Other Models</title>
<link href="../../SkinSupport/MadCap.css" rel="stylesheet" />
<link href="../../Resources/Stylesheets/BSE_Help.css" rel="stylesheet" />
<script src="../../SkinSupport/MadCapAll.js" type="text/javascript">
</script>
</head>
<body>
<div class="MCBreadcrumbsBox_0"><span class="MCBreadcrumbsPrefix">You are here: </span><a class="MCBreadcrumbsLink" href="AlphaRef.htm">PBASIC Language Reference</a><span class="MCBreadcrumbsDivider"> &gt; </span><span class="MCBreadcrumbs">Adapt BS2 Code to other Models</span>
</div>
<h1>Adapt BS2 Code to Other Models</h1>
<p>Parallax provides PBASIC code examples for many applications and devices, and many more examples can be found on the <a href="http://forums.parallax.com/forums/" target="_blank" title="Open website in new window" alt="Open website in new window">Parallax forums</a> and other web sites. While some code examples include compiler directives that make them compatible with any 24-pin BASIC Stamp model, others are written for a single model, most often the BS2. If your BASIC Stamp model is different from the one the code is written for, portions of the program may need to be adjusted to accommodate differences in processor speed. This page provides some tips and examples of how to do this.</p>
<h2>About Time-Sensitive Commands</h2>
<p class="PlainText">Many BASIC Stamp 2 application examples make use of time-sensitive commands, those which have one or more arguments that depend on some attribute of time such as frequency, duration, baud rate, decay time, or pulse duration. If the command generates a signal, one or more of its arguments may contain values that affect the signals timing. Likewise, if the command measures a signal, one or more of its arguments may affect the result. When executed by different BASIC Stamp 2 models, the units for each time-sensitive argument may differ, so if the program is not adjusted to account for these differences, signals may be generated or measured at different rates. </p>
<h3>Adjustable Time-sensitive Commands </h3>
<table cellpadding="4" cellspacing="0" border="0">
<tr>
<td>&#160;</td>
<td><a href="../Commands/COUNT.htm" target="" title="" alt="" class="MCXref_0">COUNT</a></td>
<td>
<img align="absmiddle" src="../../graphics/stamp_2family.gif" />
</td>
<td>&#160;</td>
<td><span class="keyword_in_text">COUNT</span><i> Pin, Duration, Variable</i>
</td>
</tr>
<tr>
<td>&#160;</td>
<td><a href="../Commands/DTMFOUT.htm" target="" title="" alt="" class="MCXref_0">DTMFOUT</a></td>
<td>
<img align="absmiddle" src="../../graphics/stamp_2family.gif" />
</td>
<td>&#160;</td>
<td><span class="keyword_in_text">DTMFOUT</span> Pin, {<i>OnTime, OffTime,</i> } [<i>Tone</i>
{<i>, Tone,</i> ...}]</td>
</tr>
<tr>
<td>&#160;</td>
<td><a href="../Commands/FREQOUT.htm" target="" title="" alt="" class="MCXref_0">FREQOUT</a></td>
<td>
<img align="absmiddle" src="../../graphics/stamp_2family.gif" />
</td>
<td>&#160;</td>
<td><span class="keyword_in_text">FREQOUT</span><i> Pin, Duration, Freq1</i> {, <i>Freq2</i> }</td>
</tr>
<tr>
<td>&#160;</td>
<td><a href="../Commands/POLLWAIT.htm" target="" title="" alt="" class="MCXref_0">POLLWAIT</a></td>
<td>
<img align="absmiddle" src="../../graphics/stamp_ppepx.gif" />
</td>
<td>&#160;</td>
<td><span class="keyword_in_text">POLLWAIT </span><i>Duration</i>
</td>
</tr>
<tr>
<td>&#160;</td>
<td><a href="../Commands/PULSIN.htm" target="" title="" alt="" class="MCXref_0">PULSIN</a></td>
<td>
<img align="absmiddle" src="../../graphics/stamp_all.gif" />
</td>
<td>&#160;</td>
<td><span class="keyword_in_text">PULSIN</span><i> Pin, State, Variable</i>
</td>
</tr>
<tr>
<td>&#160;</td>
<td><a href="../Commands/PULSOUT.htm" target="" title="" alt="" class="MCXref_0">PULSOUT</a></td>
<td>
<img align="absmiddle" src="../../graphics/stamp_all.gif" />
</td>
<td>&#160;</td>
<td><span class="keyword_in_text">PULSOUT </span><i>Pin, Duration</i>
</td>
</tr>
<tr>
<td>&#160;</td>
<td><a href="../Commands/PWM.htm" target="" title="" alt="" class="MCXref_0">PWM</a></td>
<td>
<img align="absmiddle" src="../../graphics/stamp_all.gif" />
</td>
<td>&#160;</td>
<td><span class="keyword_in_text">PWM </span><i>Pin, Duty, Duration</i>
</td>
</tr>
<tr>
<td>&#160;</td>
<td><a href="../Commands/RCTIME.htm" target="" title="" alt="" class="MCXref_0">RCTIME</a></td>
<td>
<img align="absmiddle" src="../../graphics/stamp_2family.gif" />
</td>
<td>&#160;</td>
<td><span class="keyword_in_text">RCTIME</span><i> Pin, State, Variable</i>
</td>
</tr>
<tr>
<td>&#160;</td>
<td><a href="../Commands/SERIN.htm" target="" title="" alt="" class="MCXref_0">SERIN</a></td>
<td>
<img align="absmiddle" src="../../graphics/stamp_all.gif" />
</td>
<td>&#160;</td>
<td><span class="keyword_in_text">SERIN</span><i> Rpin</i> {\<i>Fpin</i>}, <i>Baudmode</i>,
{<i>Plabel</i>,} {<i>Timeout</i>, <i>Tlabel</i>, } [<i>InputData</i>]</td>
</tr>
<tr>
<td>&#160;</td>
<td><a href="../Commands/SEROUT.htm" target="" title="" alt="" class="MCXref_0">SEROUT</a></td>
<td>
<img align="absmiddle" src="../../graphics/stamp_all.gif" />
</td>
<td>&#160;</td>
<td><span class="keyword_in_text">SEROUT</span><i> Tpin</i> {\<i>Fpin</i>}, <i>Baudmode</i>,
{<i>Pace</i>,} {<i>Timeout</i>, <i>Tlabel</i>,} [<i>OutputData</i>]</td>
</tr>
</table>
<p>&#160;</p>
<h2>Adapting Code with No Time-sensitive Commands</h2>
<p class="PlainText">If the BS2 application does not utilize any of the time-sensitive commands listed above, all that needs to change is the $STAMP directive. Here is an example BASIC Stamp 2 program that has no time-sensitive commands.</p><pre class="BScode" xml:space="preserve">' Hello World.bs2
' {$STAMP BS2}
' {$PBASIC 2.5}
DEBUG "Hello world!"
END</pre>
<p class="PlainText">With this program, the only change that would need to be made to get this program to run properly with a BS2sx (for example), would be to update the $STAMP directive from BS2 to BS2sx. You can either manually modify the $STAMP directive, &#160;or click the BS2sx button on the BASIC Stamp Editors toolbar (recommended).</p>
<p class="PlainText">
<img src="../../Resources/Images/BS2xsbutton.png" />
</p>
<p class="Tip" MadCap:autonum="Tip: &#160;"><span class="autonumber"><span class="TipSpan">Tip: &#160;</span></span>The BASIC Stamp Editor can detect if you are trying to load a program into a BASIC Stamp model thats different from the one indicated in the programs $STAMP directive. When this happens, it will ask you if you want it to automatically update the directive. Keep in mind that this directive update does not automatically update any time-sensitive command arguments.</p>
<h2>Adapting Code that has Time-sensitive Commands</h2>
<p class="PlainText">In addition to updating the $STAMP directive, each line of code that uses a time-sensitive command will need to be examined and possibly adjusted. The <a href="AlphaRef.htm" target="" title="" alt="" class="MCXref_0">PBASIC Command Reference</a> has links to the documentation for each command, including Quick Facts tables with the units of time-based attributes for each BASIC Stamp model. In most cases, you can use the units for the model the code is written for along with the units for the new target model to make a fraction for converting a given time-sensitive command argument. The units value for the “Convert from” model should be in the numerator, and the units for the “Convert to” model should be in the denominator. Make sure to round the “New Argument Value” to the nearest integer before using it as a command argument in a time-sensitive PBASIC command. </p>
<p>
<img src="../../Resources/Images/AdaptMath.png" />
</p>
<p class="Tip" MadCap:autonum="Tip: &#160;"><span class="autonumber"><span class="TipSpan">Tip: &#160;</span></span>The SERIN and SEROUT commands have baud rate arguments that don't use this adjustment method. The Quick Facts tables for SERIN and SEROUT have common baud rates listed, and the documentation also provides directions for calculating custom baud rates for all BASIC Stamp 2 models.</p>
<p class="PlainText">The “Old Argument Value” to “New Argument Value” calculation can be used in three different approaches for updating your code:</p>
<ol>
<li value="1">Update time-sensitive command argument constants, and/or constants that are compared to results stored in variables by time-sensitive commands.</li>
<li value="2">Calculate a re-usable multiplier for all instances of a command's argument.</li>
<li value="3">Use the results of #1 and/or #2 to set up conditional compilation directives, so the program can be run on whichever BASIC Stamp models you choose to make compatible code for.</li>
</ol>
<p class="PlainText">Lets take a look at how each approach can be used with the time-sensitive <span class="keyword_in_text">FREQOUT </span>command as an example, with the BS2 as the “Convert From” model and the BS2sx as the “Convert To” model.</p>
<h3>Approach 1- Update Time Sensitive Argument Constants</h3>
<p class="PlainText">Lets say a speaker circuit is connected to BASIC Stamp I/O pin P6. If the BS2 executes the command:</p><pre class="snippet">FREQOUT 6, 100, 4500</pre>
<p class="PlainText">... it sends a high-pitched alarm tone to the speaker for 100 ms at a frequency of 4500 Hz. A <span class="keyword_in_text">FREQOUT </span>command with the same arguments executed by the BS2sx sends a tone that only last 40 ms at a frequency of 11,250 Hz. Thats a much shorter duration tone with a much higher pitch!</p>
<p class="PlainText">The <span class="keyword_in_text">FREQOUT </span>commands Quick Facts table indicates that the <span class="keyword_in_text">FREQOUT</span> <![CDATA[ ]]><i>Duration</i> argument is in terms of 1 ms units for the BS2, and in terms of 0.4 ms units for the BS2sx. Likewise, the BS2 units for <i>Freq1</i> are 1 Hz, while the BS2sx <i>Freq1</i> units are 2.5 Hz. You can use those values and the “Old Argument Value” to “New Argument Value” equation to convert a BS2 command like:</p><pre class="snippet">FREQOUT 6, 100, 4500 </pre>
<p class="PlainText">...for use with a BS2sx. In the figure below, the existing <i>Duration</i> argument of 100 gets multiplied by 1.0/0.4 with a result of 250. Likewise, the 4500 <i>Freq1</i> argument gets multiplied by 1.0/2.5 with a nearest integer result of 1800. With these new values, the BS2sx version of the <span class="keyword_in_text">FREQOUT</span> command is:</p><pre class="snippet" xml:space="preserve">FREQOUT 6, 250, 1800</pre>
<p class="PlainText">This command is now updated to make the BS2sx deliver a 4.5 kHz tone for 100 ms.</p>
<p class="PlainText">
<img src="../../Resources/Images/AdaptFreqoutBS2sx.png" />
</p>
<h3>Approach 2 - Calculate a Re-usable Multiplier</h3>
<p class="PlainText">You can incorporate expressions with <span class="keyword_in_text">*/</span> (<a href="Ops_bi.htm#multi-mid">Multiply Middle</a>) operators to perform the conversions from approach 1 right inside a PBASIC program. The <span class="keyword_in_text">*/</span> operator allows you to multiply a constant, variable or expression result by a number of 256ths. For example, 1/4 is the same as 64/256ths, so value <span class="code_in_text">*/ 64</span> is the same as multiplying a value by 1/4. </p>
<p class="PlainText"> Each of the fractions determined with the Quick Facts table above can also be expressed as a number of 256ths. The result is “<span class="keyword_in_text">*/</span>Constant” that you can use to scale a constant, variable or expression result to adjust a command's argument for a different BASIC Stamp model.</p>
<p class="PlainTextIndent" style="font-style: normal;"><span class="keyword_in_text">*/</span>Constant = Integer(256 x (Units in “Convert From” Model / Units in “Convert To” model))</p>
<p class="PlainText">Continuing the <span class="keyword_in_text">FREQOUT </span>command example, the “<span class="keyword_in_text">*/</span>Constant” to convert <i>Duration</i> from BS2 to BS2sx units would be Integer(256 x (1/0.4)) = 640. So, a BS2 <i>Duration</i> value <span class="code_in_text">*/ 640</span> results in an approximate BS2sx <i>Duration</i> value. </p>
<p class="PlainText">Likewise, the“<span class="keyword_in_text">*/</span>Constant” for converting <i>Freq1</i> from BS2 to BS2sx is Integer(256 x (1/2.5)) = 102, and a BS2 <i>Freq1</i> <![CDATA[ ]]><span class="code_in_text">*/ 102</span> results in an approximate BS2sx <i>Freq1</i> value. You can incorporate these <span class="keyword_in_text">*/ </span>operations directly into a <span class="keyword_in_text">FREQOUT </span>commands <i>Duration</i> and <i>Freq1</i> arguments like this:</p><pre class="snippet" xml:space="preserve">FREQOUT 6, 100 */ 640, 4500 */ 102</pre>
<p class="PlainText">Keep in mind that this approach works with constants (like 100 and 4500), and it also works with variables and expression results. The only caveat is that it does take a little extra code space and execution time for each added <span class="keyword_in_text">*/</span> operation. A test program for the BS2sx with the updated <span class="keyword_in_text">FREQOUT </span>command might look like this:</p><pre xml:space="preserve" class="BScode">' Tenth Second 4.5 kHz Tone StarSlash.bsx
' {$STAMP BS2sx}
' {$PBASIC 2.5}
FREQOUT 6, 100 */ 640, 4500 */ 102
END</pre>
<p class="PlainText">Declaring constants for each of these <span class="keyword_in_text">*/</span> multipliers makes it possible to update values once at the beginning for the program for multiple <span class="keyword_in_text">FREQOUT </span>commands. With the constant declaration approach, our example program would looks like this:</p><pre class="BScode" xml:space="preserve">' Tenth Second 4.5 kHz Tone StarSlash With Constants.bsx
' {$STAMP BS2sx}
' {$PBASIC 2.5}
DurFactr CON 640
FreqFactr CON 102
FREQOUT 6, 100*/DurFactr, 4500*/FreqFactr
END</pre>
<p>&#160;</p>
<h4>Use the ** Operator for Greater Precision</h4>
<p class="PlainText">The <span class="keyword_in_text">**</span> (<a href="Ops_bi.htm#multi-high">Multiply High</a>) operator multiplies a constant, variable or expression by a number of 65536ths, up to 65535. For fractional values less than one, it provides higher resolution than the <span class="keyword_in_text">*/</span> operator. Since the fractional value for converting the <span class="keyword_in_text">FREQOUT </span>commands <i>Freq1</i> argument is less than 1, the <span class="keyword_in_text">**</span> operator can provide a more precise conversion. <br /></p>
<p class="PlainTextIndent" style="font-style: normal;">** Constant = Integer(65536 x (Units in “Convert From” Model / Units in “Convert To” model))</p>
<p class="PlainText">We can apply this to our BS2 to BS2sx <i>Freq1</i> argument conversion with:</p>
<p class="PlainTextIndent" style="font-style: normal;">** Constant = Integer(65536 x (1 / 2.5)) = 26214</p>
<p class="PlainText">Now, the <span class="keyword_in_text">FREQOUT </span>command with a more precise <i>Freq1</i> argument conversion is:</p><pre class="snippet" xml:space="preserve">FREQOUT 6, 100 */ 640, 4500 ** 26214</pre>
<p class="PlainText">How much more precise is it? The BASIC Stamp always truncates to the integer in a calculation, so </p>
<p class="PlainTextIndent">4500 */ 102 = 4500 x 102 ÷ 256 = 1792 </p>
<p class="PlainText">...truncated to the integer. For the BS2sx, that results in a frequency of 1792 x 2.5 Hz = 4480 Hz. Thats an error of 20 Hz, which is enough to be audible to sensitive ears or equipment. In contrast,</p>
<p class="PlainTextIndent"> 4500 ** 26214 = 4500 x 26214 ÷ 65536 = 1799 <![CDATA[ ]]></p>
<p class="PlainText">...truncated to the integer. This time, the BS2sx transmits a frequency of 1799 x 2.5 Hz = 4497.5 Hz, so the propagated error is now only 2.5 Hz! Here is a program that compares the tones:</p><pre class="BScode" xml:space="preserve">' Tenth Second 4.5 kHz Tone Compare StarSlash and StarStar.bsx
' {$STAMP BS2sx}
' {$PBASIC 2.5}
DurFactr CON 640
FreqFactr VAR Word
FREQOUT 6, 250, 1800 ' Calculated by hand
PAUSE 100
FreqFactr = 102 ' Multiplier for */
FREQOUT 6, 100*/DurFactr, 4500*/FreqFactr
PAUSE 100
FreqFactr = 26214 ' Multiplier for **
FREQOUT 6, 100*/DurFactr, 4500**FreqFactr
END</pre>
<p class="Tip" MadCap:autonum="Tip: &#160;"><span class="autonumber"><span class="TipSpan">Tip: &#160;</span></span>If you can't hear the difference in the tones, try multiplying each <i>Duration</i> argument by 4 with "<span class="code_in_text">4*</span>" to increase the length time you hear each tone.</p>
<h3>Approach 3 - Use Results from 1 or 2 to Set up Conditional Compilation</h3>
<p class="PlainText">The results from approaches 1 and 2 can be incorporated into <a href="ConditionalCompile.htm" target="" title="" alt="" class="MCXref_0"> Conditional Compilation</a> directives. Especially when the target BASIC Stamp module could be one of several different models, conditional compilation makes it possible to use the $STAMP directive to select which segments of code get compiled and downloaded to the BASIC Stamp. For example, code from approaches 1 and 2 can be nested into conditional compilation directives. Then, the code can be set to run in a BS2 and BS2sx by simply updating the $STAMP directive.</p>
<p class="PlainText">In this first example, the $STAMP directive identifies which BASIC Stamp model is being used at compile time, and then only the <span class="keyword_in_text">FREQOUT </span>command for the model identified gets downloaded. Note that the <span class="keyword_in_text">FREQOUT </span>command for the BS2sx uses the <i>Duration</i> and <i>Freq1</i> argument values we determined earlier in approach 1.</p><pre class="BScode" xml:space="preserve">' Tenth Second 4.5 kHz Tone Select Case.bs2
' {$STAMP BS2}
' {$PBASIC 2.5}
#SELECT $STAMP
&#160;&#160;#CASE BS2
&#160;&#160;&#160;&#160;FREQOUT 6, 100, 4500
&#160;&#160;#CASE BS2sx
&#160;&#160;&#160;&#160;FREQOUT 6, 250, 1800
#ENDSELECT
END</pre>
<p class="PlainText">In this second example (below), the <span class="keyword_in_text">*/ </span>operator is used to define constants as multipliers to apply to the <i>Duration</i> and <i>Freq1</i> arguments. These same constant symbols could be applied to any other <span class="keyword_in_text">FREQOUT&#160;</span>commands added to the program, regardless of the <![CDATA[ ]]><i>Duration</i> and <i>Freq1</i> arguments used, which could be variables, constants, or even expressions.</p><pre class="BScode" xml:space="preserve">
' Tenth Second 4.5 kHz Tone Select Case With Constants.bs2
' {$STAMP BS2sx}
' {$PBASIC 2.5}
#SELECT $STAMP
#CASE BS2
DurFactr CON 256
FreqFactr CON 256
#CASE BS2sx
DurFactr CON 640
FreqFactr CON 102
#ENDSELECT
FREQOUT 6, 100*/DurFactr, 4500*/FreqFactr
END</pre>
<p class="PlainText" xml:space="preserve">More example PBASIC programs that demonstrate conditional compilation for time-sensitive commands are included with the BASIC Stamp Editor. Just click File -&gt; Open From -&gt; Default BS2 directory, and select a program with a name like <span class="keyword_in_text">FREQOUT</span>, <span class="keyword_in_text">PULSIN</span>, or any of the other time-sensitive commands listed earlier.
</p>
<div class="Col2">
<div class="MasterFoot">
<p MadCap:conditions="BSEconditions.BSEWebHelp (Primary)-INCLUDE"><a href="../../HomeTopics/HomePage.htm">Go to Welcome page</a>
</p>
</div>
</div>
<div class="Col2">
<div class="MasterFoot">
<p style="text-align: right;"><span class="ContactInfoProjectName">BASIC Stamp Help</span> <![CDATA[ ]]><span class="ContactInfoVersion#">Version 2.5.4</span> <![CDATA[ ]]></p>
<p style="text-align: right;">Copyright ©&#160;<span class="ContactInfoCompanyName">Parallax Inc.</span></p>
<p style="text-align: right;"><span class="SystemShortDate">8/8/2012</span>
</p>
</div>
</div>
<script type="text/javascript">/* <![CDATA[ */
var _gaq = _gaq || [];
_gaq.push(['_setAccount', 'UA-285614-1']);
_gaq.push(['_trackPageview']);
(function() {
var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
})();
/* ]]> */</script>
<script type="text/javascript" src="../../SkinSupport/MadCapBodyEnd.js">
</script>
</body>
</html>