Skip to content

Latest commit

 

History

History
136 lines (108 loc) · 4.82 KB

README.md

File metadata and controls

136 lines (108 loc) · 4.82 KB
Raw

ThingSpeak Java Client

A Java client for the ThingSpeak Internet of Things. Implements all aspects of the ThingSpeak API and can be used to update channel data, retrieve and examine feeds, and query public channels. It supports the hosted ThingSpeak server at api.thingspeak.com as well as self-hosted open-source servers (GitHub Source).

Also included: An appender for log4j - post data to ThingSpeak channels using Logger framework.

How To Install

Get the source by downloading a zip file or by cloning the git repository https://github.com/angryelectron/thingspeak-java.git . Building the source requires the Java 7 SDK and Apache Ant, or use the Netbeans IDE.

Here is an example of how to install the client from the command line in Ubuntu/Debian/Raspbian with a minimal build environment:

sudo apt-get update
sudo apt-get -y install openjdk-7-jdk git ant
git clone https://github.com/angryelectron/thingspeak-java.git
cd thingspeak-java
ant

To run optional tests, run 'ant test'. Due to the rate limit of the public Thingspeak server (15sec), tests can take a long time to run. After building, the jars, docs, and dependencies can be found in thingspeak/dist.

How To Use

Add thingspeak-x.y.jar to your project and the following dependencies:

Dependencies can be found in thingspeak/dist/lib after building the source. Refer to the included javadocs for more details. The ThingSpeak API Documentation is also a good source of additional information about using the API.

If you encounter any issues with the ThingSpeak Java Client, please use the GitHub issue tracker.

Examples

Here is how to write "hello" to field1 of ThingSpeak public channel 1234, then read it back.

import com.angryelectron.thingspeak.*;

public class ThingExample {

    public static void main(String[] args) throws Exception {
        String apiWriteKey = "your-channel-write-key";
        Channel channel = new Channel(1, apiWriteKey);        
        try {            
            // write something
            Entry writeEntry = new Entry();
            writeEntry.setField(1, "Hello");            
            // read it back
            Entry readEntry = channel.getLastChannelEntry();
            System.out.println(readEntry.getField(1));
        } catch(Exception ex) {
            System.out.println(ex);
        } 
    }
    
}

Please refer to thingspeak/dist/javadoc for more information about customzing channel feeds, searching public channels, using open-source servers, and all the other operations supported by the ThingSpeak API.

log4j Appender

Use log4j to update ThingSpeak channels. Date, Level, and Message are 'fields', written as an 'entry'. Setup a new ThingSpeak channel with these three fields, then pass the channel number and API write-key to the appender.

Here's how to configure the appender and send a test message (just add your own channelNumber and apiWriteKey):

ThingSpeakAppender appender = new ThingSpeakAppender();
appender.configureChannel(channelNumber, apiWriteKey, "http://api.thingspeak.com");
appender.setThreshold(Level.INFO);
appender.activateOptions();
Logger.getRootLogger().addAppender(appender);
Logger.getLogger(this.getClass()).log(Level.INFO, "Hello World");

You can also configure the appender via log4j.properties:

log4j.rootLogger=INFO, ThingSpeak
log4j.appender.ThingSpeak=com.angryelectron.thingspeak.log4j.ThingSpeakAppender
com.angryelectron.thingspeak.log4j.channelNumber = YOUR_CHANNEL_NUMBER
com.angryelectron.thingspeak.log4j.apiWriteKey = YOUR_API_WRITE_KEY

To use your own server (other than api.thingspeak.com):

com.angryelectron.thingspeak.log4j.server = YOUR_THINGSPEAK_SERVER_URL

See the javadocs for more details.

About

The ThingSpeak Java Client is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

The ThingSpeak Java Client is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with the ThingSpeak Java Client. If not, see http://www.gnu.org/licenses/.