Firmware for different busware.de gadgets Copyright Rudolf Koenig, 2008,2009 License: GPL v2 These gadgets all feature one or more CC1101 transceiver and an Atmel MCU, so the can be used for low-power wireless communication in the 868 band. - The CUL (CC110x USB Light) has one CC1101 and an AT90USB162 MCU. See http://busware.de/tiki-index.php?page=CUL for details and on how to buy it. - The CUR (CC110x USB Remote) is a device with following features: CC1101 / AT90USB646 / 16Mbit flash / 128x128 color display / 5-way jogdial / Battery. - The CUN (CC110x USB Network) is a device with following features: CC1101 / AT90USB1287 / Ethernet interface / 16Mbit flash / 256Kbit SRAM / MicroSD - The CSM (CC110x Serial Module) is a device you talk to a serial way using a host system with an USART available. I/O lines are 3.3V or 5V safe - ATMEGA88/168/328(P) This firmware makes it possible to use these devices with fhem. Right now the following RF protocols are supported: - FS20 - FHT - EM - KS300/S300TH - HMS Thanks to the MyUSB project (http://www.fourwalledcubicle.com/MyUSB.php, ) the device/firmware combination confirms to the Universal Serial Bus Communication Device Class Abstract Control Model (USB CDC ACM) specification, so it can be used out of the box with a lot of operating systems. Prerequisites ============= You'll need following packets to install the firmware (in paranthesis is the version of the corresponding packet for my installation): - dfu-programmer (0.4.4) If you want to modify the firmware: - avr-libc (1.6.2) - binutils-avr (2.18) - gcc-avr (4.3.0) Compile (optional) ================== Change into your device directory (e.g. Devices/CUL) Type "make", which will output text like: Compiling C: CUL.c [...] Install / Flash the firmware ============================ Change into your device directory (e.g. Devices/CUL) - CUL/CUN: Insert the USB-Stick while pressing the micro-switch on the back. - CUR: Remove Battery/USB. Put the device on a table with the jogdial facing down. Press the case, until you hear the jogdial is pressed. Insert the battery, then the USB-Cable. A USB device "03eb:2ffa Atmel Corp." should appear. Now execute "make usbprogram", which will output text like: dfu-programmer at90usb162 erase dfu-programmer at90usb162 flash CUL.hex Validating... 6312 bytes used (51.37%) dfu-programmer at90usb162 start The last command will reset the device, a new USB device should appear: "03eb:204b Atmel Corp.". If not try to reinsert the CUL without pressing the micro-switch. Quick Test: =========== Linux ===== Hopefully you see a device /dev/ttyACM0 (if you use a newer kernel, which loads the cdc_acm kernel module), or a /dev/ttyUSB0 (if your kernel uses usbserial). For usbserial kernel you may need to add the module options "usbserial vendor=0x03eb product=0x204b" to modprobe.conf. Connect to the device e.g. with "screen /dev/ttyACM0". Windows ======= Install a virtual COM port, use MyUSB_USBtoSerial.inf from the docs directory. Locate the COM-port in the device manager shown as "USB Virtual Serial Port (COMx)". Start Hyperterminal, open a connection to COMx 9600,8,n,1. CUN: Connect the device to a network with a DHCP server, and then telnet to the assigned address with "telnet 2323" Type "V". The string "V 1..." should appear. Type X21 to enable the RF data reporting. culfw<->PC Protocol (over USB or TCP/IP) ======================================== The data is readable ASCII with cr/nl as a message terminator. PC -> culfw: ---------- The first byte is the command (case significant), the rest ist command dependent, usually a hex string, case insignificant. Commands are _not_ echoed. Following commands are supported (alphabetic list): a[] (CUR only) If no YY is specified: - Display the battery state: XX = 01 raw reading XX = 00 reading transformed into %, taking nonlinearity into account If both XX and YY is specified (CURV3 only): XX = 00 Charge with 500mA (YY=01) or 100mA (YY=00) XX = 01 Disable USB charging (YY=01) or enable it (YY=00) B Reboot device. If is not 00 enter bootloader mode (for flashing the device see the install section above) C is a (two digit) hex number: return the value of the cc1101 register. =99 dumps the first 48 registers. Example: C35 -> C35 = 0x0D / 13 c (CUR/CUN ) Read/set the clock: either the RTC chip (CUR only) or the internal NTP counter (CUN only). If hex is 01, then display the date, if it is 02 the time, if it is 03, then both date and time. If the length of hex is 6, then the RTC will be set to YYMMDDHHmmSS. Data is written BCD, i.e December is written as 12 and not as 0C. The RTC version of the clock may be set partially: if hex is 6 characters long (converted to 3 bytes) then only the time part will be set. This is not applicable to NTP. ddata (CUR only) Choose the sub-function with the first two bytes (hex): - FF: LCD control, the next 3 bytes (6 chars) are: - LCD on (01) / on+cls (02) / off (00) / don't change (FF) - contrast: set directly (00-FE) / read from eeprom (FC) / increase (FE) / decrease (FD) / don't change (FF) - brightness: set directly (00-FE) / read from eeprom (FC) / increase (FE) / decrease (FD) / don't change (FF) - 00: Set the title to the string following the 00 - 01-08: Set the "body" lines 01-08 the the text - 09/0A: Insert a new line at the bottom/top of the screen, scrolling the rest. E eth debugging (CUN only) - c Print out the currently configured IP & MAC Adress. - d increase the debug level. Meaning of the levels 1: application debugging, e.g. the NTP module will display the time 2: print ETH header (mac adress + ETH frametype) 3: dump whole ethernet packet. - i Reinitialize the ethernet subsystem, restart DHCP & NTP - n Request an NTP update e (eeprom) factory reset resets all eeprom values. e causes a reboot to activate all changes. "ex" will reset the eeprom values without a reboot, this is for internal use only. f[] Experimental "fast" (250kBaud) rf txmit via CC1101 packet handling. First switch both devices to fastrf mode with "fr", then send data: fs, e.g. fsHallo Reset to "SlowRF": fx, followed by X21 F Send out an FS20 message. is a hex string of the following form: hhhhaacc or hhhhaaccee, where - hhhh is the FS20 housecode, - aa is the FS20 device address, - cc is the FS20 command - ee is the FS20 timespec. Note that cc must have the extension bit set. Example: F12340111 l Set the led mode. - 00: Set LED off - 01: Set LED on - 02: The LED will blink once a second P (CUR only) Display a picture. The hex part consists of 4 bytes (x,y,w,h), and the file contains the data in a 12bit per pixel format. Use fonts/pgm2fourbit.pl with the raw option to convert raw PPM files into the needed format, and tools/cur_file.pl to upload the file R or R Read eeprom (i.e. "saved configuration") byte. Arguments: one or two byte hex address or Adress-Slots: - 0x00 - 0x01 Eeprom magic bytes - 0x02 - 0x2A Configuration registers as described in the "Table 37: "SPI Address space" of the CC1101 datasheet (Version SWRS061C). Note: all EEPROM Values have an offset of 2. - 0x2B - 0x32 CC1101 PA Table (8 bytes). See fncollection.h for more details. Example: R00 -> 63 For the additional CUN-only settings see the corresponding W (write eeprom) section. r (CUR/CUN) Display the file from the builtin 2MB flash. First the length of the file, (hex 8 byte+nl) is written to the output, then the body of the file. Use "." as filename to get a listing of the current files with length. Use the program cur_file from the tools directory to read a file, e.g.: perl cur_file.pl -r MENU /dev/ttyACM0 NOTE: No fhem/screen must be connected to the CUR while reading/writing s (CUR only) sleeptime. Switch everything off after seconds of joystick inactivity. An instant sleep is achieved by pressing the joystick. 00 disables sleep. If the CUR is connected via USB then only the display will be switched off. THHHHCCOOAA FHT commands - HHHH FHT80b housecode - CC FHT80b: command, FHT8v:Valve address, 00-08 - OO FHT80b: origin (CUL:77 or FHT:67), FHT8v: Command - AA Command argument Store the message in the FHT80b or FHT8v buffer, and communicate with the corresponding 80b/8v when the timeslot arrives. 8v commands are specified by setting HHHH to the "own" housecode. For command details see fhem/FHEM/11_FHT.pm Special control commands for the CUL: - T01 Set the "own" housecode to HHHH. The first byte will be used as the FHZ code in in FHT80b mode. This command will also clear all buffers. Note: if HHHH is 0000, then FHT80b communication is switched off. - T01 Return the own housecode (hex) - T02 Return the FHT80b buffer. FHT80b commands are queued in the internal buffer, which has place for 14 to 31 messages. - T03 Return the size of the remaining FHT80b buffer (bytes, hex). - T10 Return the FHT8v buffer. There is one value per 8v address. - T11 Return the time till the next 8v timeslot (seconds, hex) t Output the time since boot (uptime). The output is a hex number, resolution is 1/125 sec. An overflow occures every 397 days. u RF_ROUTER functionality A CUL can funtion as a router, by sending/receiving data to/from a remote CUL via RF. So it is possible to extend the range by plugging additional CULs int to the socket, and configure them to send their data to the local (i.e. PC-connected) CUL. - u (without parameter) Display the own and the router id, both one byte hex. - uiRRBB Set the own/rfr id, and the base id (the id of the CUL connected to fhem). If RR is not 00, the RF_ROUTER functionality is enabled. If BB is not 00, the RF reception is enabled at start (X21) and all received messages (FS20/FHT/etc) are relayed to the CUL with id BB. Messages arrive on the base CUL (with id BB) with the prefix BBRRU see the exampe below. - uRRBB Send to the CUL with ID from the sender BB. will be executed as a local command on the remote CUL. Answers will be sent (only!) to the configured router and not the BB id specified in this command. - ud (if compiled with RFR_DEBUG) display the current ticks, and the ticks for the scheduled rf_router answer. Used to check if rf_router is working - us (if compiled with RFR_DEBUG) Statistics: Number of sent messages in categories. The categories are: F.T.E.K.H.x.#, x beeing the rest and # the number of delayed transmissions due to current rf reception. All numbers are 16bit counters. Example: ui0601 (configure remote CUL) ui0100 (configure local CUL) u0601V -> 0106UV 1.34 CUL868 u0601C35 -> 0106UC35 = 0D / 13 V Print the firmware version. Example: V -> V 1.30 CUL868 W
or W
Write eeprom (i.e configuration) byte. Arguments: one or two-byte hex address followed by one byte hex data
. See R above for address (AAAA) explanation. Example: W1D06 Additional CUN-only commands: Wim - MAC Address Wid - DHCP enabled flag Wia - IPV4 Address Wig - IPV4 gateway Win - IPV4 network mask Wip - tcplink port WiN - NTP sever Wio - GMT offset Notes: - Factory reset: use DHCP, port 2323, NTP-Server = Router, GMT offset:0 - Everything becomes active only after a reboot. - MAC adress is written as hex, with optional semicolon - IP4 adresses are written in decimal with dot separator - port is written in decimal - if the NTP server is 0.0.0.0 (default), then the router is used as an NTP server. - the GMT offset is specified as a hex number, and is a signed value: ff==-1, fe==-2, etc - factory reset will re-initialize this data, with a unique MAC address - If DHCP is enabled, the left (orange RX/TX) led blinks till a valid DHCP adress is received. Example: Wim01:02:03:04:05:06 Wia192.168.0.1 Wio02 w (CUR/CUN) write the file named to the 2MB onboard flash. Length is hex, 8 bytes. The command must be followed by length bytes of data, which will be written to the local file. If length is FFFFFFFF, then the file will be deleted. Use the program cur_file.pl from the tools directory to write a file, e.g.: perl cur_file.pl -w MENU /dev/ttyACM0 NOTE: _NO_ fhem/screen must be connected to the CUR while reading/writing Special control commands for the CUL: - w01 enables event logging to the file Syslog.0, w00 disables it. Factory reset is disabled, as writing to the log is relatively slow, and the CUN/CUR may skip RF messages. - wformat will reformat the flash (== writes the superblock) X Enable data reporting. is a one-byte hex value, with following bits (bit 0 is the LSB bit): - Bit 0: Report known messages (parity & checksum ok), with type prefix. - Bit 1: Report each of the (repeated) packets of a message - Bit 2: Report detailed data, even with wrong parity / checksum. - Bit 3: Monitor mode: output an r on a risings edge and 'f' on a falling edge. Output a '.' at the end of the message (no signal for 4msec). - Bit 4: Timing: in monitor mode output one additional byte of the internal microsecond timer, divided by 16. This is binary! - Bit 5: RSSI: report RSSI value as an additional HEX byte after digested data or as a separate byte if Bit 3 is set too. - Bit 6: Report FHT protocol messages (ack, etc) - Bit 7: CUL/CUN: Report raw RSSI data (a==weak ... p==strong signal) CUR: Grafic representation: dark==weak ... light == stong signal Note: 00 disables radio reception, any other value initialize the radio chip and enable reception. Default is 00: do not report anything, radio chip uninitialized. Example: X01 (normal reporting, no RSSI) or X67 (debugging) If is not specified, report the current value and the available time for sending RF (in 10 ms units) x Change the (EEPROM) PA tables (power amplification for RF sending) is a one-byte hex value, valid values are 00 to 09, with following values: the first 5 is -10/-5/0/5/10 dBm without PA ramping, the next 5 is the same with PA ramping. If the value is outside this spec, then the 5dBm variant (03) will be used. Notes: - after changing the value (in the EEPROM) an X command (X21) will be necessary to write the EEPROM changes to the CC1101. - The default CUL_V2 firmware has no PA ramping compiled in (see board.h) Example: x03 q Terminate the TCP/IP session (CUN only) Unknown commands Prints the "help", the list of supported commands Example: z -> ? (z is unknown) Use one of B C F R T V W X e f l t x culfw -> PC: ------------ The CUL reports following data (as a HEX string, uppercase): For FS20: Fhhhhaacc or Fhhhhaaccee, explanation see above. For FHT: ThhhhNNNNNN For EM: Ettaacc111122223333 tt:type 01=EM-1000s, 02=EM-100-EM, 03=1000GZ aa:address, depending on the type above 01:01-04, 02:05-08, 03:09-12 cc:counter, will be incremented by one for each message 1111: cumulated value 2222: last value (Not set for type 2) 3333: top value (Not set for type 2) For KS300: KFFTTTHWHWWRRFR Data must be read backwards For S300TH: KaaTTHTHH Data must be read backwards For HMS: Hxxxxxxxxxxxx For Hoermann Garage door openers: Rxxxxx Note: this protocol is not really understood. If bit 3 in the X command is set, then report raw data, even if it has a wrong checksum or parity. The format is: p State zhi zlo ohi olo NSync NByte Nbit [RSSI] NNNN State Internal state of the state machine zhi avg. high-time of the zero bit zlo avg. low- time of the zero bit ohi avg. high-time of the one bit olo avg. low- time of the one bit Nsync Number of 0 sync bits Nbyte Number of whole bytes received Nbit Number of bits (last partial byte) RSSI RSSI, if the RSSI bit is set, see X cmd NNNN Raw data with parity/checksum, without sync. CUR Menu -------- To define a menu on the CUR, follow this HOWTO: - create a fhem xml-list with fhem.pl fhemhost:7072 xmllist > fhem.xmllist - convert the template and the fhem listing into a CUR MENU file: perl xmllist2curmenu.pl fhem.xmllist CUR.menu.template > MENU - write the MENU file to the CUR: perl cur_file.pl -w MENU /dev/ttyACM0 NOTE: The CUR must be in the X00 mode (default after reboot), and no fhem/screen should be connected to it. - switch the CUR display on by pressing the joystick. - To have a nice logo on the first screen, upload it to the CUR: cd fonts perl ../tools/cur_file.pl -w house2_58x60 /dev/ttyACM0 Notes ===== - 1% LIMIT The firmware respects the 1% limit for this band, i.e. only 160 FS20 messages per hour will be sent. See the second number returned by the "X" command for the remaining send-time (in 10 ms units). This time is updated once a second. - Repeat-filter The FS20 protocol sends each message 3 times. The firmware filters optionally (See Command X bit 3) repeated messages. - cc1100 settings. See cc1100.h / official PDF from TI for details. - Change receiver sensitivity / target amplitude AGCCTRL2 (0x1B), bits 2:0, target amplitude: 0:24dB, 1:27dB, 2:30dB, 3:33dB, 4:36dB, 5:38dB, 6:40dB, 7:42dB Default value: C1B -> 07 (42dB). AGCCTRL0 (0x1D), bits 1:0, decision boundery 0:4dB, 1:8dB, 2:12dB, 3:16dB Default value: C1D -> 91 (8db) Example: W1D06 Notes: - fhem users can set these values with "set CUL rAmpl 42 sens 8" - R/W address (EEPROM) for the FS20/SlowRF Communication is = CC1101 address+2, for the FastRF Communication is CC1101 address+55. See fncollection.h for other values. - Change frequency FREQ2(0D), FREQ1(0E), FREQ0(0F), Fosc = 26MHz Fcarrier = Fosc/65536*(FREQ2.FREQ1.FREQ0) Example: W0F21, W1065, W11E8 (868.35MHz, default) W0F21, W1062, W1176 (868.00MHz) Note: fhem users can set it with "set CUL freq 868.3" - Change channel bandwidth MDMCFG4 (10). CHANBW_E (bits 7:6), CHANBW_M (bits 5:4) BWchannel = Fosc/(8 * (4+CHANBW_M) * 2 ^ CHANBW_E) Example: W1255 (325KHz, default) W1245 (406KHz) W1235 (464KHz) Note: fhem users can set it with "set CUL bWidth 325" - Read-Only-Registers: RSSI: : C34 -> 217 (217-256-74 = -113 dBm) MARCSTATE: C35 -> 01 (Idle), 13 (RX) TODO/Known BUGS: ========== - CU* Setting time sometimes changes the date too - CU* rf_router: fhem module, execute cmd, test - CU* FS20 dim commands do not repeat. - CUR Xfer&Display plots from fhem - CUR fhem MENU/files creation support - CUR umlauts - CUR sleep problems: FS20 1%-management