Difference between revisions of "RS-485 Library"
| (16 intermediate revisions by the same user not shown) | |||
| Line 2: | Line 2: | ||
The BoSL RS-485 Bus library creates utilities to abstract the use of the RS-485 Bus hardware [[RS-485]] It facilitates the communication of use of multiple sensors over one RS-485 line to ensure that clear communication is achieved and no bus collisions occur. The library is set up to be easily added to an existing sketch code see the annotate examples for inspiration. A fundamental idea of the library are that sensors should only be awake when in use and should otherwise be asleep in a minimal power mode, hence it has been optimized to use minimal power with a proper implementation drawing <5μA when in sleep mode. It enables both high and low level interfacing with the RS-485 sensor, so if you want to forget about the nuances RS-485 and have that manged automatically that is possible and so is getting down to control the specific pins to interface with the RS-485 line driver directly. | The BoSL RS-485 Bus library creates utilities to abstract the use of the RS-485 Bus hardware [[RS-485]] It facilitates the communication of use of multiple sensors over one RS-485 line to ensure that clear communication is achieved and no bus collisions occur. The library is set up to be easily added to an existing sketch code see the annotate examples for inspiration. A fundamental idea of the library are that sensors should only be awake when in use and should otherwise be asleep in a minimal power mode, hence it has been optimized to use minimal power with a proper implementation drawing <5μA when in sleep mode. It enables both high and low level interfacing with the RS-485 sensor, so if you want to forget about the nuances RS-485 and have that manged automatically that is possible and so is getting down to control the specific pins to interface with the RS-485 line driver directly. | ||
| + | |||
| + | It should be noted the behavior of the reset pin is not yet implemented. The idea would be to not reset the sensors if possible so as to not waste time on waiting for the processors to reset before a measurement can be recorded. This time can be upwards of 0.5s! | ||
== Implementation == | == Implementation == | ||
| Line 8: | Line 10: | ||
Place the src folder in the same folder as your arduino .ino sketch. <br> | Place the src folder in the same folder as your arduino .ino sketch. <br> | ||
Edit RS485args.h (located inside the src folder) to fit setup. | Edit RS485args.h (located inside the src folder) to fit setup. | ||
| + | |||
| + | In RS485args.h the following should be edited to match setup:<br> | ||
| + | *HOST should be set to 0 if the device is a sensor and 1 if the device is a host. <br> | ||
| + | *TX should be the pin number of the serial TX pin for the device. <br> | ||
| + | *RX should be the pin number of the serial RX pin for the device. <br> | ||
| + | *WKE (host only ) should be the pin number for the pin controlling the WKE line of the BoSL RS485 Bus. <br> | ||
| + | *DE should be the pin connected to the write enable on the RS485 line driver. <br> | ||
| + | *RE should be the pin connected to the read enable on the RS485 line driver. | ||
| + | |||
| + | This completes the implementation need to be done in files outside the .ino file | ||
| + | |||
| + | For implementation of a host or a sensor inside the .ino file please see the annotated examples below. | ||
| + | |||
| + | UPLOADING firmware is different to the use of the device for instructions on how to upload firmware to an RS-485 sensor please have a read of [[RS-485]] | ||
== Downloads == | == Downloads == | ||
| Line 18: | Line 34: | ||
Sensor Sketch (rev 1.0.0 | 2020-09-18) : [[File:Sensor.zip]] | Sensor Sketch (rev 1.0.0 | 2020-09-18) : [[File:Sensor.zip]] | ||
| − | == | + | == Interface Protocol == |
| − | |||
=== Command Packet === | === Command Packet === | ||
A command packet is an easy and safe way to send commands from the host to a sensor. It is implemented to automatically take care of waking of sensors, and only a small about of user code is needed to handle the auto-sleep after a command is issued. | A command packet is an easy and safe way to send commands from the host to a sensor. It is implemented to automatically take care of waking of sensors, and only a small about of user code is needed to handle the auto-sleep after a command is issued. | ||
| − | The structure of a command packet is a wake | + | The structure of a command packet is a wake event followed by 4-bytes of data. The wake event consists of a 1 μS pulse of the WKE line low. This is sufficient to wake up the ATmega328p microcontroller. Following this 9 mS is waited for the sensors to have sufficient time to wake from sleep. 4 bytes of data are then sent over the bus. The first byte, addr, signifies the device address, after this byte has been received send all the sensors which do not have this address may return to sleep. The 2nd byte, opp, signifies the intended operation for the sensor. The operations are to be implemented on a sensor to sensor level however preferred names of standard operations are defined below. The 3rd and 4th bytes are named parA and parB. These are two bytes which can carry additional information about the operation. They have no specific defined use and can be used for however useful. |
| − | === | + | <!-- In fact the command packet is not only able to be used over RS-485. The library should be flexible enough to have this work over plain Serial. So this may still be a useful protocol to use if you want a quick way to transfer data from a non-rs485 sensor that you are prototyping. --> |
| + | |||
| + | === Device Address === | ||
| + | |||
| + | The device address may take any value from 0x00 - 0xFE inclusive. The 0x00 device address shall be reserved for the host device. 0xFF is reserved as an internal error and so shall not be used as a device address. | ||
| + | device addresses are defined in software at runtime. A device may change its address during operation however this is unadvised. | ||
| + | |||
| + | A table of currently used addresses is included below to help with address space management. | ||
| + | |||
| + | {| class="wikitable" | ||
| + | |- | ||
| + | ! Address !! Use | ||
| + | |- | ||
| + | | 0x00|| Host | ||
| + | |- | ||
| + | | 0x01 || testing use | ||
| + | |- | ||
| + | | 0xFF || Reserved | ||
| + | |} | ||
| + | |||
| + | === Suggested Operation Names === | ||
The table below lists sensible names for operations that would be universal to different sensors. They are not necessary to be adhered to. | The table below lists sensible names for operations that would be universal to different sensors. They are not necessary to be adhered to. | ||
{| class="wikitable" | {| class="wikitable" | ||
| Line 37: | Line 72: | ||
| I || Get sensor info | | I || Get sensor info | ||
|} | |} | ||
| + | |||
| + | == Library Methods == | ||
| + | === begin === | ||
| + | |||
| + | === listen === | ||
| + | |||
| + | === endlisten === | ||
| + | |||
| + | === sleep === | ||
| + | === wake === | ||
| + | === available === | ||
| + | === checktransmitt === | ||
| + | === getaddress === | ||
| + | === wakedevices === | ||
| + | === completeTx === | ||
| + | === write === | ||
| + | === print === | ||
| + | === println === | ||
| + | === sendcmd === | ||
| + | === read === | ||
| + | === parsecmd === | ||
| + | === getcmd === | ||
| + | === getparA === | ||
| + | === getparB === | ||
Latest revision as of 06:40, 12 August 2021
Here is a page devoted to the RS-485 BoSL implementation library.
The BoSL RS-485 Bus library creates utilities to abstract the use of the RS-485 Bus hardware RS-485 It facilitates the communication of use of multiple sensors over one RS-485 line to ensure that clear communication is achieved and no bus collisions occur. The library is set up to be easily added to an existing sketch code see the annotate examples for inspiration. A fundamental idea of the library are that sensors should only be awake when in use and should otherwise be asleep in a minimal power mode, hence it has been optimized to use minimal power with a proper implementation drawing <5μA when in sleep mode. It enables both high and low level interfacing with the RS-485 sensor, so if you want to forget about the nuances RS-485 and have that manged automatically that is possible and so is getting down to control the specific pins to interface with the RS-485 line driver directly.
It should be noted the behavior of the reset pin is not yet implemented. The idea would be to not reset the sensors if possible so as to not waste time on waiting for the processors to reset before a measurement can be recorded. This time can be upwards of 0.5s!
Implementation
Extract the src folder from the downloaded .zip file.
Place the src folder in the same folder as your arduino .ino sketch.
Edit RS485args.h (located inside the src folder) to fit setup.
In RS485args.h the following should be edited to match setup:
- HOST should be set to 0 if the device is a sensor and 1 if the device is a host.
- TX should be the pin number of the serial TX pin for the device.
- RX should be the pin number of the serial RX pin for the device.
- WKE (host only ) should be the pin number for the pin controlling the WKE line of the BoSL RS485 Bus.
- DE should be the pin connected to the write enable on the RS485 line driver.
- RE should be the pin connected to the read enable on the RS485 line driver.
This completes the implementation need to be done in files outside the .ino file
For implementation of a host or a sensor inside the .ino file please see the annotated examples below.
UPLOADING firmware is different to the use of the device for instructions on how to upload firmware to an RS-485 sensor please have a read of RS-485
Downloads
Library
Revision 1.0.0 (2020-09-18) : File:BoSL RS485 Bus Library rev 1.0.0.zip
Annotated Examples
Host Sketch (rev 1.0.0 | 2020-09-18) : File:Host.zip
Sensor Sketch (rev 1.0.0 | 2020-09-18) : File:Sensor.zip
Interface Protocol
Command Packet
A command packet is an easy and safe way to send commands from the host to a sensor. It is implemented to automatically take care of waking of sensors, and only a small about of user code is needed to handle the auto-sleep after a command is issued.
The structure of a command packet is a wake event followed by 4-bytes of data. The wake event consists of a 1 μS pulse of the WKE line low. This is sufficient to wake up the ATmega328p microcontroller. Following this 9 mS is waited for the sensors to have sufficient time to wake from sleep. 4 bytes of data are then sent over the bus. The first byte, addr, signifies the device address, after this byte has been received send all the sensors which do not have this address may return to sleep. The 2nd byte, opp, signifies the intended operation for the sensor. The operations are to be implemented on a sensor to sensor level however preferred names of standard operations are defined below. The 3rd and 4th bytes are named parA and parB. These are two bytes which can carry additional information about the operation. They have no specific defined use and can be used for however useful.
Device Address
The device address may take any value from 0x00 - 0xFE inclusive. The 0x00 device address shall be reserved for the host device. 0xFF is reserved as an internal error and so shall not be used as a device address. device addresses are defined in software at runtime. A device may change its address during operation however this is unadvised.
A table of currently used addresses is included below to help with address space management.
| Address | Use |
|---|---|
| 0x00 | Host |
| 0x01 | testing use |
| 0xFF | Reserved |
Suggested Operation Names
The table below lists sensible names for operations that would be universal to different sensors. They are not necessary to be adhered to.
| Operation Name | Function |
|---|---|
| P | Poll sensor measurement |
| S | Sleep (if not automatic) |
| I | Get sensor info |
