SHC Base Station

Base Station

Purpose

The base station is the master of your SHC network. It communicates to every other device and controls it. It's connected to a PC (or router or NAS etc.) and serves as gateway to your normal home (W)LAN. The data connection is typically implemented through a USB-to-serial converter.

The SHC specific network protocol including encryption and retries is implemented in the base station. But it is no stand-alone device. The higher level logic like feedback loops and control sequences are not defined in the base station, but have to be defined in a server program on the connected PC. This concept is chosen to allow changing control flows easily without the need to reflash the base station. Additionally, there are several good other projects for this purpose and the SHC base station can be integrated into them easily.

In addition to using the received data to control other devices, another common use case is to create statistics.

Communication with the Base Station

When you connect the base station over a serial port to your PC, you can control it with some simple commands. The device may be connected to a physical serial port or over a virtual com port provided by a USB-to-serial converter.

After switching on the base station, you are greeted with the following prompt:

smarthomatic Base Station v0.9.0
(c) 2012..2015 Uwe Freese, www.smarthomatic.org
Device ID: 0
Packet counter: 700
AES key count: 2
UART baud rate: 115200
Waiting for incoming data. Press h for help.

UART Baud Rate

You can choose a baud rate of 19200 (default) and 115200 (fast) by setting an e2p value. Because printing characters on the serial line takes time when sending and receiving packets over the base station, the fast setting reduces these times. There is a typical delay of ~95ms when sending a packet with the default baud rate. Although this should already be considered fast, this time can be reduced to ~18ms with the fast baud rate (times measured from last character entered by the user to the request to the RFM12 to send the packet). When a packet is received, the fast baud rate also speeds up printing the data to the serial line (where it is received by the server application, e.g. FHEM) accordingly.

Receiving Data

If a data packet is received, you can see the raw packet data and the decrypted data.

Received (AES key 0): 5c 8c e1 69 01 70 17 05 d8 14 3d 8f 00 00 00 00
Packet Data: SenderID=23;PacketCounter=94301;MessageType=8;MessageGroupID=10;MessageID=1;MessageData=ec7800000000;Temperature=21.67;Humidity=54.32;Brightness=21;

From v0.10.0 on, it is printed in an abbreviated form:

PKT:SID=31;PC=45642;MT=8;MGID=10;MID=2;MD=724215000000;45b678e6
Detected Weather_HumidityTemperature_Status: Humidity=45.7;Temperature=21.32;
Received (AES key 0): 11 c3 34 92 01 f0 0b 24 a8 14 4e 48 42 a0 00 00

The packet header and header extension is decoded and the according header fields are listed (orange), using the basic packet layout definition. The message data is a series of bytes listed as a hex string (green).

The first line is suffixed with a CRC32 (violet). If the server software (e.g. FHEM) detects a CRC error because of interferences/problems on the serial line, it should ignore the whole packet. The CRC32 is calculated over the string beginning with the 5th character (the S from SID) and ending with the ; before the CRC.

If the MessageGroup and MessageID are known to the base station, the individual values of the message are listed as well (red). But this is not possible with new messages the base station doesn't know. Therefore, only the data string should be used in the end user software and the values should be decoded there, using the packet_layout.xml file. Consider the listing of individual values as a debugging help only.

Sending Requests

You can directly send packets by entering the data as listed in the help:

*** Help ***
h..............this help
rAA............read EEPROM at hex address AA
wAAXX..........write EEPROM at hex address AA to hex value XX
x..............enable writing to EEPROM
z..............disable writing to EEPROM
sKK{T}{X}{D}...Use AES key KK to send a packet with MessageType T, followed
               by all necessary extension header fields and message data.
               Fields are: ReceiverID (RRRR), MessageGroup (GG), MessageID (MM)
               AckSenderID (SSSS), AckPacketCounter (PPPPPP), Error (EE).
               MessageData (DD) can be 0..17 bytes with bits moved to the left.
               End data with ENTER. SenderID, PacketCounter and CRC are automatically added.
sKK00RRRRGGMMDD...........Get
sKK01RRRRGGMMDD...........Set
sKK02RRRRGGMMDD...........SetGet
sKK08GGMMDD...............Status
sKK09SSSSPPPPPPEE.........Ack
sKK0ASSSSPPPPPPEEGGMMDD...AckStatus

As you can see, the AES key number used to encrypt the data packet is entered as first element. It's necessary to use the correct key so the device you want to control can decrypt it. After the message type follow the header extension fields and the message data (if any). These fields depend on the message type you want to send. Again, please look into the basic packet layout and Message Catalog for details.

The CRC32 checksum, SenderID (of the base station) and PacketCounter are added automatically. If you send a request, the packet is added to the request queue automatically before sending.

And here's an example sending a "Set" to a Power Socket:

** Enter AES key nr, MessageType, header extension + data in hex format to send, finish with ENTER. ***
Processing command: s00010028140180
Data byte 0 = 128
Request added to queue.
Request buffer 0: MessageType 1, PacketCounter 0, Timeout 1, Retry 0, Data 02 82 83 00 00
Request Queue 0: ReceiverID 40, Buffer slots 0 - - -

Repeating request.
Packet Data: SenderID=0;PacketCounter=3401;MessageType=1;ReceiverID=40;MessageGroupID=20;MessageID=1;MessageData=8000000000;On=1;TimeoutSec=0;
       AES key: 0
   Unencrypted: e3 b5 0c 8d 00 00 00 d4 91 02 82 83 00 00 00 00
Send encrypted: 25 35 52 e9 29 42 a1 55 3d 4d de bd a7 6f 1b f0

E2P Device Configuration

As you can see below, there are several AES keys stored in the device specific config block. Only these AES keys are used in the BaseStation firmware. The AES key in the Generic block is not used.

OffsetBlockContentTypeSizeDescription
0Hardware
Values for hardware setup, which have no special meaning to SHC device concepts + the DeviceType, which decides about the existence of further blocks.
DeviceTypeEnumValue1 BytesThe device can check with this value if the EEPROM data is meant for the actual type of device. If not, the device goes into an error mode.
Values: 0 = BaseStation, 20 = EnvSensor, 40 = PowerSwitch, 50 = RGBDimmer, 60 = Dimmer, 70 = SoilMoistureMeter, 80 = Thermostat, 90 = TeaMaker
8OsccalModeIntValue1 BytesThis value is used to change the speed of the internal oscillator. 0 = don't use OSCCAL calibration (e.g. external crystal oszillator is used). -128 = OSCCAL measure mode: the LED blinks every 60s, so the user can measure the original speed. -127..+127 = The speed is adjusted by the given amount in per mill (e.g. 10 means to speed up the device by +1%).
MinVal: -128, MaxVal: 127, Default: 0
16Reserved6 Bytesn/a
64Generic
This block contains SHC configuration data which every device has.
DeviceIDUIntValue12 BitsThe DeviceID identifies the specific unit in the SHC network. It is used to address the device and in messages the device sends. Every device has to have a different DeviceID.
MinVal: 0, MaxVal: 4095
76Reserved4 Bitsn/a
80PacketCounterUIntValue3 BytesThe PacketCounter is counted up throughout the whole lifetime of the device and is used to make the encrypted packets differently from each other every time.
MinVal: 0, MaxVal: 16777215
104Reserved19 Bytesn/a
256AesKeyByteArray32 BytesThis key is used to encrypt packets before sending and also used as primary key to decrypt packets. Special devices may have additional keys in their device specific block.
512BaseStation
This block contains the specific configuration data that only Base Station devices need.
AesKeyCountUIntValue1 BytesThis is the number of AES keys to use from the AesKeys block. Limit the number to the needed amount to avoid that the base station tries decoding with every one.
MinVal: 1, MaxVal: 16, Default: 1
520AesKeyByteArray[16]32 Bytes x 16These are all AES keys which can be used to encrypt or decrypt packages at the base station.
4616UartBaudRateEnumValue1 BytesSelect which baud rate to use for communication with the base station. Use 19200 (0,2% baud rate error @20 MHz) for standard speed, which should work with any connected device. Use 115200 (1,4% baud rate error @20 MHz) to speed up communication to the base station.
Values: 19 = 19200, 115 = 115200, Default: 19
4624Reserved446 Bytesn/a

Hardware Overview

PCBConventional THTThrough hole technology This is the conventional technique to stick pins of components through the PCB and solder them. This is easy to build up, unlinke using SMD components. (non-SMD)
Generic Maxi Speed PCB
50 x 50 mm
MicrocontrollerATMega 328A-PU (28-pin PDIP)
Clock Source20 MHz external crystal
Special ComponentsUSB-to-serial connector
RFM Transceiver ModeRX + TX
UARTRX + TX, usually connected to a PC with a USB-to-serial converter
PowerUSB 5V (+ internal 3.3V regulator)

Schematic

Layout

Download

Assembly Instructions

Look into the Wiki for assembly instructions for this device. It would be appreciated if you correct or enhance the description whenever you find potential for improvement.